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.
FIN_BASE_URL=https://api.example.test
FIN_API_KEY=your_api_key
FIN_USER_ADDRESS=0x0000000000000000000000000000000000000001 # the wallet your user signed in with1. 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.
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.
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 for each controller.
If your app has no login
Let the user sign in with their wallet instead. Ask for a sign-in message:
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.jsonHave the user sign message exactly as returned. With viem in the browser:
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:
FIN_SIGNATURE='<the wallet 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.json3. Get the main conversation
Every user has a main conversation. Single-chat apps send every message there.
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.
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.
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). To let the agent find recipients by name, add the user's saved contacts as context.contacts from your server (see 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 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.
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.
Or poll the run instead of streaming:
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.
- Read it with Get an approval and show the user exactly what it will do: the assets, amounts, destination and limits it lists.
- If it moves money, it carries
authorization.message. Have the user sign that message with their wallet. - Send the decision: Approve an action (with
authorization: {controllerId, expiresAt, signature}for a money action) or Deny an action. 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 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.
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.
- Read Get a question. Render each question's prompt and options, one question at a time. Only
multiple: truepermits multiple options. - Collect an answer for each question the user answers: its
idand selected optionvalues, orvalues: []withcustomText(up to 2,048 characters). Custom text and option values are mutually exclusive. A question the user skips gets no answer. - Call Answer a question with a fresh UUID
Idempotency-Keyand{ "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: users, conversations, runs, approvals and money.
- Streaming and events: history and reconnecting.
- Deposits, withdrawals and trades: funding the agent and taking money out.
- Automations: tasks the agent runs on its own.
- Errors: every refusal and what to do about it.