> ## Documentation Index > Fetch the complete documentation index at: https://docs.circuit.org/llms.txt > Use this file to discover all available pages before exploring further. # Read the user's link > Returns when the permit ends, the wallets the user picked with their holdings, and their running agents. Pass `chat` to get a chat with Ask's replies and proposals, and `include=agents` to get the agents the user can start. While `retry_after_ms` is set, read again after that many milliseconds. Safe to repeat. ## OpenAPI ````yaml /partner-openapi.gen.json get /partner/v0.1 openapi: 3.1.0 info: title: Circuit partner API version: '0.1' servers: - url: https://api.circuit.org security: [] paths: /partner/v0.1: get: summary: Read the user's link description: >- Returns when the permit ends, the wallets the user picked with their holdings, and their running agents. Pass `chat` to get a chat with Ask's replies and proposals, and `include=agents` to get the agents the user can start. While `retry_after_ms` is set, read again after that many milliseconds. Safe to repeat. operationId: read parameters: - name: chat in: query required: false schema: description: A chat to return, starting with `chat_`. type: - string - 'null' examples: - chat_7d3e1a90-4b2c-4e5f-8a6b-1c2d3e4f5a6b example: chat_7d3e1a90-4b2c-4e5f-8a6b-1c2d3e4f5a6b - name: include in: query required: false schema: description: Send `agents` to also return the agents the user can start. examples: - agents example: agents anyOf: - oneOf: - description: The agents the user can start. type: string const: agents - type: 'null' responses: '200': description: OK content: application/json: schema: description: >- The user's link to your app: their wallets, running agents and, when asked for, a chat and the agents they can start. type: object properties: permit_expires_at: $ref: '#/components/schemas/Timestamp' description: >- When the permit ends. Send the user a new link before then to keep their agents running. wallets: description: >- The wallets the user picked for your app. Empty when they picked none and use paper money only. type: array items: $ref: '#/components/schemas/Wallet' sessions: description: >- The user's running agents on those wallets and on paper money, newest first. type: array items: $ref: '#/components/schemas/Session' chat: description: >- The chat you asked for with `chat`, oldest message first. Null when you asked for none. anyOf: - $ref: '#/components/schemas/Chat' - type: 'null' agents: description: >- With `include=agents`: the agents the user can start. Circuit's agents, popular community agents and the user's own; the agents most people started in the last 30 days come first, and Circuit's agents come first among equals. Null otherwise. type: - array - 'null' items: $ref: '#/components/schemas/Agent' retry_after_ms: description: >- While Ask is answering in that chat or one of its proposals is being carried out, how many milliseconds to wait before reading again. Null when nothing is in progress. type: - integer - 'null' format: uint64 minimum: 0 required: - permit_expires_at - wallets - sessions default: description: Failed content: application/json: schema: $ref: '#/components/schemas/PartnerFailure' security: - permit: [] components: schemas: Timestamp: type: string format: date-time Wallet: description: A wallet the user picked for your app. type: object properties: id: description: The wallet's id, starting with `wal_`. type: string name: description: The name the user gave the wallet. type: string address: description: The wallet's onchain address. type: string value_usd: description: >- Total value in USD as a decimal string. Null when a holding could not be priced. type: - string - 'null' holdings: description: >- Everything the wallet holds: tokens, perps, prediction shares and lending positions. type: array items: $ref: '#/components/schemas/PartnerHolding' required: - id - name - address - holdings Session: description: An agent running for the user on one wallet or on paper money. type: object properties: id: description: The session's id, starting with `ses_`. type: string agent: description: The agent it runs, starting with `agt_`. type: string name: description: The agent's name. type: string wallet: description: >- The wallet it trades, starting with `wal_`. Null when it runs on paper money. type: - string - 'null' status: $ref: '#/components/schemas/PartnerSessionStatus' value_usd: description: >- The current value of what the session holds, in USD as a decimal string. Null until Circuit first values a new session, about a minute after it starts, or when a holding can't be priced. type: - string - 'null' pnl_usd: description: >- Profit or loss since the session started, in USD as a decimal string. Null when unknown. type: - string - 'null' error: description: >- What the user needs to do when `status` is `needs_user`. Null otherwise. type: - string - 'null' started_at: $ref: '#/components/schemas/Timestamp' description: When the session started. required: - id - agent - name - status - started_at Chat: description: A chat between the user and Ask Circuit. type: object properties: id: description: The chat's id, starting with `chat_`. type: string messages: description: Every message in the chat, oldest first. type: array items: $ref: '#/components/schemas/Message' required: - id - messages Agent: description: >- An agent the user can start: a published program that trades on its own schedule. type: object properties: id: description: The agent's id, starting with `agt_`. Pass it to start a session. type: string name: description: The agent's name. type: string description: description: One line on what the agent does. Null when its creator wrote none. type: - string - 'null' official: description: True when Circuit made the agent. type: boolean yours: description: True when the user made the agent. type: boolean return_percent: description: >- How much its sessions have returned since they started, as a decimal percent. Null when unknown. type: - string - 'null' paper: description: >- True when the agent can run on paper money, false when it needs real money. Null for a few seconds after its creator publishes a new version, while Circuit checks it. type: - boolean - 'null' people: description: How many people started this agent in the last 30 days. type: integer format: int32 start: description: >- What a start gives the agent. Null when it declares no starting asset. anyOf: - $ref: '#/components/schemas/AgentStart' - type: 'null' required: - id - name - official - yours - people PartnerFailure: description: >- A failed call. Handle it by HTTP status and `code`, and show `error` to the user. type: object properties: error: description: A message you can show the user. type: string code: description: >- A stable code such as `BAD_REQUEST`, `INSUFFICIENT_BALANCE`, `NOT_FOUND`, `CONFLICT` or `UNAUTHORIZED`. New codes can appear. type: string required: - error - code PartnerHolding: description: One asset or position in a wallet. type: object properties: symbol: description: The asset, such as `BTC` or `USDC`. type: string network: description: >- Where it is held, such as `ethereum:8453`, `solana`, `hypercore` or `lighter`. type: string kind: description: >- What it is: `token`, `perp`, `prediction`, `supplied` or `borrowed`. New kinds can appear. type: string amount: description: The amount as a decimal string. Negative for a short or a debt. type: string value_usd: description: Value in USD as a decimal string. Null when Circuit cannot price it. type: - string - 'null' required: - symbol - network - kind - amount PartnerSessionStatus: oneOf: - description: The agent is running on its own schedule. type: string const: running - description: >- The agent is running but the user needs to do something. `error` says what, for example that the permit ends soon. type: string const: needs_user - description: The agent was stopped. Its positions stay open. type: string const: stopped Message: description: One message in a chat and Ask's reply to it. type: object properties: id: description: The message's id, starting with `msg_`. type: string chat: description: The chat it belongs to, starting with `chat_`. type: string status: $ref: '#/components/schemas/MessageStatus' text: description: What the user wrote. Null when Circuit followed up on its own. type: - string - 'null' reply: description: Ask's reply in Markdown. Null while Ask is still working. type: - string - 'null' proposals: description: >- Trades, agent starts and top-ups that Ask proposed in this reply. Each needs your approval. type: array items: $ref: '#/components/schemas/PartnerProposal' required: - id - chat - status - proposals AgentStart: description: The asset a start or top-up gives an agent; `amount` is in this asset. type: object properties: symbol: description: The asset, such as `USDC`. Null when Circuit has no symbol for it. type: - string - 'null' network: description: >- Where it is held, such as `ethereum:8453`, `solana` or `hypercore`, as in a holding. type: string minimum: description: The least a start takes, as a decimal string. type: string required: - network - minimum MessageStatus: oneOf: - description: Ask is still writing its reply. type: string const: working - description: The reply is complete. type: string const: done - description: Ask could not answer. `reply` says why. type: string const: failed PartnerProposal: description: >- Something to carry out: a trade or agent change Ask proposed, or a start, top-up or stop you sent. type: object properties: id: description: The proposal's id, starting with `prop_`. type: string chat: description: >- The chat it belongs to, starting with `chat_`. Read the link with it to follow the proposal. type: string title: description: >- What it does, starting with a verb, such as "Buy 0.04 ETH on Lighter" or "Start Macro Trend". type: string status: $ref: '#/components/schemas/PartnerProposalStatus' error: description: Why it failed when `status` is `failed`. Null otherwise. type: - string - 'null' session: description: >- The session it started or changed, starting with `ses_`. Null for trades. type: - string - 'null' amounts: description: >- The amounts it shows the user on Circuit: what it moves, or for `USD` what it spends or its notional. Empty when it shows none. type: array items: $ref: '#/components/schemas/ProposalAmount' required: - id - chat - title - status - amounts PartnerProposalStatus: oneOf: - description: Waiting for you to approve or decline it. type: string const: review - description: Approved, and Circuit is carrying it out. type: string const: processing - description: Carried out. type: string const: done - description: Declined, or it expired before anyone approved it. type: string const: declined - description: It could not be carried out. `error` says why. type: string const: failed ProposalAmount: description: One amount a proposal moves. type: object properties: symbol: description: >- The asset, such as `ETH` or `USDC`, or `USD` for a dollar amount. Null when unknown. type: - string - 'null' network: description: >- Where it is, such as `ethereum:8453`, `solana` or `lighter`. Null when unknown. type: - string - 'null' amount: description: >- The amount as a decimal string. Negative when it leaves the wallet in a swap. type: string value_usd: description: >- Value in USD as a decimal string. Null when Circuit has no value for it. type: - string - 'null' required: - amount securitySchemes: permit: type: http scheme: bearer description: The permit the user approved for your app. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.