F Fin / Overview v1 Guides OpenAPI
API v1

Build on an agent that holds
the user's funds.

Fin runs an agent for each of your users: it reads their portfolio, answers questions, and executes what they approve. Your backend calls it with your partner key and the user's own token, and nothing moves money until that user has approved the exact terms.

Quickstart API reference OpenAPI document

Quickstart

  1. AuthenticateSend your key as X-Api-Key and the user's token as Authorization. Neither works alone.
  2. Provision the accountOne idempotent POST /v1/users. It is the only call an unprovisioned identity may make.
  3. Open a conversation and start a runA run is accepted with 202 and works in the background.
  4. Follow the journalStream the conversation, and answer any approval.opened the run parks.
# 1. provision (idempotent)
curl -X POST $FIN/v1/users \
  -H "X-Api-Key: $KEY" -H "Authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' -d '{}'

# 2. open a conversation
curl -X POST $FIN/v1/users/$USER/sessions ... \
  -d '{"title":"Portfolio check"}'

# 3. ask for something
curl -X POST $FIN/v1/users/$USER/sessions/$SESSION/runs ... \
  -d '{"text":"What is my USDC balance?"}'

# 4. follow it live
curl -N $FIN/v1/users/$USER/sessions/$SESSION/stream ... \
  -H 'accept: text/event-stream'

Before you build

Authentication

Two credentials on every request, and why a partner key can never act for a user on its own.

Errors

RFC 9457 problems: what reason means, which are retryable, and the request id to quote.

Events

The journal every conversation writes, and the stream that replays it live.

Compatibility

What can change inside /v1 without warning, and what never will.

Browse by resource

Users

Provisioning and reading the account behind a verified identity.

3 operations

Conversations

Conversations: create, list and read them, and the activity feed across them.

8 operations

Runs

Starting, reading and stopping the agent's work on a conversation.

3 operations

Events

A conversation's durable journal, as pages or as a live stream.

2 operations

Approvals

Tool calls parked for the user's decision.

4 operations

Files

Files attached to a conversation.

3 operations

Agent wallet

The user's agent wallet: its balances, and withdrawals to the owner.

6 operations

Budget

Spend headroom for the current day and month.

1 operation

Automations

Standing rules that fire on a schedule or an event, and the sources they may watch.

14 operations

Guides

Concepts

The pieces — users, the wallet, conversations, runs and approvals — and how they fit.

Concepts

The journal and the stream

What a conversation's event history is, and how the live stream relates to it.

Concepts

Quickstart

Provision a user, run the agent, and follow it to a result — including a parked approval.

Tutorials

All guides

Concepts, tutorials and reference prose that go beyond one endpoint at a time.