> ## 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. # Act for the user > Does one thing for the user: sends what they wrote to Ask Circuit, starts, tops up or stops an agent, or approves or declines a proposal. Returns the message or proposal it created or changed. Starts, top-ups, stops and approvals take effect immediately, so send them only after the user confirms in your app. Send an `Idempotency-Key` and resend with the same key if the network fails; Circuit then acts once. Approving or declining again returns the proposal unchanged, and the opposite decision on a decided proposal returns 409. ## OpenAPI ````yaml /partner-openapi.gen.json post /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: post: summary: Act for the user description: >- Does one thing for the user: sends what they wrote to Ask Circuit, starts, tops up or stops an agent, or approves or declines a proposal. Returns the message or proposal it created or changed. Starts, top-ups, stops and approvals take effect immediately, so send them only after the user confirms in your app. Send an `Idempotency-Key` and resend with the same key if the network fails; Circuit then acts once. Approving or declining again returns the proposal unchanged, and the opposite decision on a decided proposal returns 409. operationId: act parameters: - name: idempotency-key in: header required: false schema: description: >- A UUID your app generates for this act. Send the same value when you retry, and Circuit acts once and returns the first result. Reusing a key with different contents returns 409. Without a key, a retried act can happen twice. type: string format: uuid requestBody: required: true content: application/json: schema: description: >- One thing to do for the user. Starts, top-ups, stops and approvals take effect immediately, so send them only after the user confirms in your app. oneOf: - description: >- Send what the user wrote to Ask Circuit. Ask answers in the background; read the link with the chat to get the reply. type: object properties: say: type: object properties: chat: description: >- The chat to continue, starting with `chat_`. Null starts a new chat. type: - string - 'null' examples: - null text: description: What the user wrote. type: string examples: - Long $50 of ETH on Lighter at 3x required: - text additionalProperties: false required: - say additionalProperties: false - description: >- Start an agent on a wallet the user picked, or on paper money. type: object properties: start: type: object properties: agent: description: The agent to start, from `agents` in the link. type: string examples: - agt_0b3c9e2a-6d1f-4f7a-9c2e-5b8a1d4e7f60 wallet: description: >- The wallet it should trade, from `wallets` in the link. Null runs it on paper money. type: - string - 'null' examples: - null amount: $ref: '#/components/schemas/NonnegativeDecimal' description: >- How much of the agent's `start` asset to give it, as a decimal string. examples: - '100' required: - agent - amount additionalProperties: false required: - start additionalProperties: false - description: Add more of a running agent's starting asset. type: object properties: top_up: type: object properties: session: description: The session, starting with `ses_`. type: string examples: - ses_48213 amount: $ref: '#/components/schemas/PositiveDecimal' description: >- How much of the agent's `start` asset to add, as a decimal string. examples: - '50' required: - session - amount additionalProperties: false required: - top_up additionalProperties: false - description: Stop a running agent. Its open positions stay open. type: object properties: stop: type: object properties: session: description: The session, starting with `ses_`. type: string examples: - ses_48213 required: - session additionalProperties: false required: - stop additionalProperties: false - description: >- Carry out something Ask proposed, after the user agreed in your app. type: object properties: approve: type: object properties: proposal: description: The proposal, starting with `prop_`. type: string examples: - prop_cd968859-fe26-4c0a-953e-34a3ab68171b required: - proposal additionalProperties: false required: - approve additionalProperties: false - description: Drop something Ask proposed. type: object properties: decline: type: object properties: proposal: description: The proposal, starting with `prop_`. type: string examples: - prop_cd968859-fe26-4c0a-953e-34a3ab68171b required: - proposal additionalProperties: false required: - decline additionalProperties: false responses: '200': description: OK content: application/json: schema: description: >- What an act created or changed: a message to Ask, or a proposal. oneOf: - $ref: '#/components/schemas/Message' type: object properties: kind: type: string const: message required: - kind - $ref: '#/components/schemas/PartnerProposal' type: object properties: kind: type: string const: proposal required: - kind default: description: Failed content: application/json: schema: $ref: '#/components/schemas/PartnerFailure' security: - permit: [] components: schemas: NonnegativeDecimal: type: string maxLength: 80 pattern: ^(?:0|[1-9]\d*)(?:\.\d+)?$ PositiveDecimal: type: string maxLength: 80 pattern: ^(?:[1-9]\d*(?:\.\d+)?|0\.\d*[1-9]\d*)$ 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 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 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 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 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.