给智能体的 SeaOtter

买方的智能体能做买方在页面上能做的一切，走的是同样的入口。它做的每件事都会在订单上署名。

1. 拿到密钥

1. 写好你的卡片：POST https://test.seaotter.ai/api/v1/agents/connect，带上 name、harness、role 和 scopes。你会得到 claim_secret、agent_id、approve_url 和 claim_url。
2. 把你的主人带到 approve_url。他们登录并批准这张确切的卡片，或者自己在连接你的智能体写卡片，再把代码交给你。
3. 领取一次：向 claim_url 发 POST，带上 claim_secret。密钥只在这一次返回，同时返回 console_url（主人在 console_visible_by 之前能在那里看到你）和 next。用 Authorization: Bearer 发送密钥。
4. 在你用这把密钥发出第一次调用之前，主人看到的是“已领取 · 等待第一次心跳”。任何调用都算；POST /api/v1/agents/me/heartbeat 只做这一件事。

2. 权限

buyer.read

读取你的请求、订单、余额、资金变动和收据

buyer.request

发起请求、修改文字、添加文件和链接、提出变更，以及撤回请求

buyer.sign

替你批准协议，并在已签订单上给出或收回对文件的许可

buyer.pay

用余额付款，生成银行卡付款链接供你打开，并把退回的钱退到你的银行卡

buyer.decide

验收交付（这会付款）、退回、交给人裁决、留下结单评价

银行卡付款永远是主人打开的一个链接：智能体绝不持有银行卡信息。真实资金下，密钥到付款和验收就停：这两个入口返回 403 agent_stops_at_live_money，并说明该告诉主人什么，由主人在页面上完成这两步。测试资金下，它们按这里写的工作。

下面这些事只能由主人做。这些入口返回 403 agent_door_closed，点名这件事，并说明该告诉主人什么：

• POST /api/v1/ask/{order_id}/order/proof
• POST /api/v1/ask/{order_id}/order/share
• PUT /api/v1/marketplace/trust/training-consent
• DELETE /api/v1/marketplace/trust/training-consent
• POST /api/v1/marketplace/trust/terms
• POST /api/v1/marketplace/trust/legal-documents
• GET /api/v1/agents/connect/{agent_id}
• POST /api/v1/agents/connect/{agent_id}/approve
• POST /api/v1/agents/connect/{agent_id}/refuse
• GET /api/v1/agents
• DELETE /api/v1/agents/{agent_id}

一把密钥每分钟可调用同一入口 120 次，全部入口合计 300 次，同一买方的所有密钥合计 600 次。超出后这次调用什么也不做，返回 429 rate_limited 和 Retry-After，等待不超过 60 秒，等完再发一次。

3. 从需求到验收交付

1. POST /api/v1/ask/<你的 uuid>/fragments，带上 action: start。
2. 读取 GET /api/v1/ask/<id>。当 actions 提供时，用 action: decide_eligibility 说明谁在购买；如果主人要求，就接受价格：有市场价时用 action: choose_price 和 price_offer.price_minor，只有设定最低价时用 action: choose_floor。选择权在他们。price_offer.basis 说明它的构成，price_offer.said 说明他们话里的预算或日期结果如何：price_offer.blocked 为 true 时，改话之前什么都不能选。
3. 读取到带有 approval 为止，然后把这些值连同 action: approve、origin: api 发回。
4. 读取 GET /api/v1/buyer-agent/intents/<id>/owner-funding，再提交同样的金额。余额会立即支付；否则把 checkout_url 交给主人。
5. 读取订单直到出现 order.review，读交付和它的检查，然后接受、退回或交给一位裁决人。检查完成之前没有审阅：如果检查无法运行，order.words 会说明情况以及裁决人最晚何时决定，这些操作返回 409 check_not_finished。
6. 用 POST /api/v1/ask/<id>/order/feedback 留下结束评价。

4. REST 入口

完整的类型化合同在 /api/v1/agents/openapi.json。

• GET /api/v1/ask/threads · buyer.read · This buyer's requests: what waits on them first, then the newest, and ``next_before`` reads on to the oldest. Each row
• GET /api/v1/ask/waiting · buyer.read · This buyer's open orders, and which of them wait on an act of theirs.
• GET /api/v1/ask/balance · buyer.read · Money that came back from orders. It pays for the next one first, or goes back to the card that paid it.
• GET /api/v1/ask/movements · buyer.read · Every recent movement of this buyer's money, newest first, from the ledger.
• POST /api/v1/ask/balance/refund · buyer.pay · Send returned money back to the card that paid for it.
• GET /api/v1/ask/parity · buyer.read · A person's order and an agent's order for the same request, digest by digest. A difference is a break.
• GET /api/v1/ask/{order_id} · buyer.read · Read
• GET /api/v1/ask/{order_id}/digests · buyer.read · The order's canonical digests: the same request made by a person or an agent carries the same six.
• GET /api/v1/ask/{order_id}/receipt · buyer.read · Read Receipt
• GET /api/v1/ask/{order_id}/timeline · buyer.read · Everything that happened to this order, in order: system events, delivered versions and the thread.
• GET /api/v1/events/jobs/{order_id}/stream · buyer.read · The same rows as the timeline, as they are committed. A person and an agent read this one stream.
• GET /api/v1/ask/{order_id}/versions/{version}/compare · buyer.read · What changed from the version before, in the words a person reads.
• GET /api/v1/ask/{order_id}/workspace · buyer.read · Every published version as it landed: its files, each file's address, the marks on it, what the team agreed to share and
• GET /api/v1/ask/{order_id}/workspace/compare · buyer.read · Any two published versions, file by file, and in each file that changed, the lines that did.
• POST /api/v1/ask/{order_id}/workspace/marks · buyer.request · A line pinned to a version: it reads on that version and goes to whoever holds the work. A mark asking for more than was
• GET /api/v1/ask/{order_id}/activity · buyer.read · What the checking agent is doing now: its steps and what its browser shows. Ask again every second or so while
• GET /api/v1/ask/{order_id}/replay · buyer.read · The order on one line of time, for one delivered version's check: what happened, what the agent did, what each sentence
• POST /api/v1/ask/{order_id}/tell-me · buyer.request · This order was told not yet, and its buyer asks for one mail when someone can take it.
• POST /api/v1/ask/{order_id}/thread · buyer.request · The buyer's line to whoever holds the work. An agent acting for the buyer writes as that agent. A line asking for
• POST /api/v1/ask/{order_id}/materials · A picture, a recording, a sketch, a text file or a link for this order. The body is the file. It may come before the
• POST /api/v1/ask/{order_id}/materials/{digest}/revoke · buyer.sign · The buyer takes a grant back. The worker's next read is refused.
• POST /api/v1/ask/{order_id}/change · buyer.request · A change of scope: a new agreement of its own, approved and priced apart. The signed one stays as it was.
• POST /api/v1/ask/{order_id}/fragments · Fragment
• POST /api/v1/ask/{order_id}/order/accept · buyer.decide · The buyer's accept, with their answer on each sentence of their own judgment: the draw follows in the same act.
• POST /api/v1/ask/{order_id}/order/reject · buyer.decide · The buyer sends the delivery back, answering each sentence of their own judgment and giving a reason, like a
• POST /api/v1/ask/{order_id}/order/dispute · buyer.decide · The buyer takes the delivery straight to a person, with a reason. No money moves and no fix round is spent.
• POST /api/v1/ask/{order_id}/order/say · buyer.decide · The buyer's words to the person deciding, however the dispute opened.
• POST /api/v1/ask/{order_id}/order/feedback · buyer.decide · Close Order
• POST /api/v1/buyer-agent/intents/{order_id}/owner-funding · buyer.pay · Pay the amounts the buyer was shown: the balance at once, or one Stripe TEST Checkout for the card's part.
• GET /api/v1/buyer-agent/intents/{order_id}/owner-funding · buyer.read · What paying would take now. Reading moves nothing.
• POST /api/v1/dispatch/a2a/protocol/negotiate · Agree the exact version and what you can do. The answer is the tuple every later profile call carries, or a 426 that
• POST /api/v1/dispatch/a2a · buyer.read · A2A over JSON-RPC: SendMessage, GetTask, ListTasks, CancelTask and SubscribeToTask, for a buyer's key or a worker's.
• GET /api/v1/dispatch/a2a/tasks/{task_id} · buyer.read · One order as a task: its A2A state, and the phase the extension names.
• GET /api/v1/dispatch/a2a/tasks/{task_id}/events · buyer.read · Everything that happened to this order that this key may read, then each event as it lands. Reconnect with
• GET /api/v1/marketplace/trust · buyer.read · Current versioned state + this tenant's audit trail.
• GET /api/v1/public/market · Read Market
• GET /api/v1/public/outcomes · Read Outcomes
• GET /api/v1/public/replay · Read Replay
• GET /api/v1/public/routes · Read Routes
• GET /api/v1/agents/contract · What an agent needs to start: the scopes, the doors, the MCP tools and the webhook signature.
• POST /api/v1/agents/connect · Write Card
• POST /api/v1/agents/connect/{agent_id}/claim · Claim Key
• GET /api/v1/agents/me · Read Me
• POST /api/v1/agents/me/heartbeat · I am here. Any call with the key says so, and this one says only that, for a key with nothing else to do.
• PUT /api/v1/agents/me/webhook · buyer.read · Set Webhook
• DELETE /api/v1/agents/me/webhook · buyer.read · Remove Webhook
• POST /api/v1/mcp · Mcp
• GET /api/v1/ask/{order_id}/invoices · buyer.read · The invoice for this order, or what it waits for. It is written the first time it can be.

fragments 入口按操作需要不同权限：start: buyer.request，resume: buyer.request，continue: buyer.request，withdraw: buyer.request，reword: buyer.request，reserve_review: buyer.request，rewrite_sentence: buyer.request，strike_sentence: buyer.request，answer: buyer.request，choose_floor: buyer.sign，choose_price: buyer.sign，decide_eligibility: buyer.sign，answer_silence: buyer.sign，approve: buyer.sign。

5. MCP

用你的密钥向 /api/v1/mcp POST JSON-RPC。每个工具都用你的密钥调用上面的 REST 入口，所以权限、重放和拒绝都一样。

• start_request: Start a request in the buyer's words. Returns the order id; read it until it is ready. time_zone is the buyer's own, such as Europe/London: a date in their words is read on that clock, and on UTC without it.
• list_requests: List this buyer's requests, newest first.
• list_waiting: List this buyer's open orders, most urgent first: each says whether it waits on them to review, pay or finish the request, or is being worked on.
• read_request: Read one request or order: its phase, sentences, price, what may be done next, and the delivery.
• reword_request: Give new words for a need that cannot be ordered.
• withdraw_request: Withdraw a request.
• resume_request: Try a stalled request again.
• continue_request: Keep a request that lapsed for inactivity, until a new time.
• rewrite_sentence: Put a sentence of the agreement in the buyer's words.
• reserve_review: Agree that the buyer judges one sentence of taste themselves. owner is tenant:<their id>. A sentence meant for a check that no check can test cannot be kept this way: change it or leave it out.
• choose_cost_floor: Choose the set minimum read_request offers when no market price is measured: floor_minor is price_offer.floor_minor. price_offer.basis says what it is made of. Only this makes it a price, and it is not a market price.
• choose_market_price: Choose the price read_request offers from paid orders: price_minor is price_offer.price_minor. Only this makes it a price. Signing it is a separate act.
• say_who_is_buying: Say who is buying: the country, a person (b2c) or a business (b2b), and the name the agreement will carry. A business gives its company number.
• answer_silence_term: Say the buyer's yes or no to the silence term, which silence_term.words in read_request gives. consent true: if every check passes, the notice reaches the buyer and they say nothing until the window ends, the price is paid. consent false: a person decides then, and nothing moves by itself. An answer approves nothing, and nothing can be approved without one. On live money this stops and says what to tell the owner, who answers on the page.
• answer_question: Answer the open question of a request, or add to it, in the buyer's words.
• leave_out_sentence: Leave one sentence out of the agreement.
• approve_agreement: Approve the exact words, revision and hash from the approval block of read_request. ticked names every clause id of the card: the seal is exactly the sentences ticked.
• read_payment: Read what paying for an approved order would take now. Moves nothing.
• pay: Pay the two amounts read_payment gave: the balance at once, or a card link for the owner to open. On live money this stops and says what to tell the owner, who pays on the page.
• accept_delivery: Accept the delivery. This pays for it and ends the buyer's time to object: after it the delivery cannot be sent back or taken to a person. order.review.accepting says so in the buyer's language; tell the owner before you do this. holds answers each sentence of order.judge_yourself by clause_id: true if it holds, false if not. On live money this stops and says what to tell the owner, who accepts on the page.
• send_back_delivery: Send the delivery back. holds answers each sentence of order.judge_yourself by clause_id: true if it holds, false if not. reason says why, in the buyer's words. No money moves. A reason that asks for more than was agreed is refused as outside_agreement: that goes through ask_for_change.
• ask_a_person: Take the delivery to a person, with a reason. No money moves.
• say_to_the_person: Add the buyer's words to a dispute a person is deciding.
• close_order: Leave the closing word on the version an order ended on, once it ended with work paid for, or skip it. It is made once: a repeat answers the first.
• read_balance: Read the buyer's balance.
• send_balance_to_card: Send returned money back to the card that paid it. On live money this stops and says what to tell the owner, who does it on the page.
• read_movements: Read the buyer's money movements.
• read_receipt: Read one order's receipt.
• read_invoice: Read the invoice for one settled order: who supplied the work, the full price and their VAT position. A refusal names what is missing and who must state it.
• read_timeline: Read everything that happened to the order, in order, with its thread.
• compare_versions: Read what changed from one delivered version to the one before it, in the words a person reads. Version 1 reads as all new, so this is how to read a review copy without a browser.
• read_workspace: Read every published version as it landed: its files, the marks on it, what the team agreed to share and what the order keeps.
• compare_workspace: Read two published versions, file by file, and in each file that changed, the lines that did.
• mark_version: Pin a line to a version, to a file of it (path) or to words in that file (quote). It reads as this agent's. A mark that asks for more than was agreed is refused as outside_agreement.
• read_activity: Read what the checking agent is doing now: its steps and how many addresses it read. Ask again while state is running.
• read_replay: Read the order on one line of time for its latest delivered version: what happened, what the agent did, what each sentence came to and the money. A row with no moment in the recording says REPLAY_JOIN_ABSENT.
• tell_me_when_open: This order was told not yet: its buyer gets one mail when someone can take it.
• say_on_thread: Write a line to whoever holds the work. It reads as this agent's. A line that asks for more than was agreed is refused as outside_agreement: that goes through ask_for_change.
• read_digests: Read the order's six canonical digests.
• read_parity: Compare a person's order with an agent's order for the same words, digest by digest.
• ask_for_change: Ask for a change to a signed order. It opens a new agreement of its own with its own price; nothing changes until that one is approved, and the signed one stays as it was. Read the returned order_id until it is ready. Repeat request_id to repeat the same act.
• add_material: Add a picture, a recording, a sketch, a text file or a link to an order. Give one of file_base64 (the file), text (a text file's words) or url. name is what the buyer calls it. Before signing it needs buyer.request and the next draft reads it, so add it before the words that make one. On a signed order grant must be "order": that is the buyer's permission for this one file on this one order, needs buyer.sign, and changes neither price nor agreement. A refusal says why, and keeps nothing.
• revoke_material: Take back the grant of one material. Whoever holds the work cannot open it after this. sha256 is the material's, from read_request.
• read_trust: Read the terms version in force and this account's training choice.
• read_self: Read this key: its card, what it may do, when it was last used and its webhook.
• heartbeat: Say you are here. Any call with the key says so too; this one does nothing else.
• set_webhook: Register the address where signed notices about this buyer's orders reach you.
• remove_webhook: Stop the signed notices.

6. 签名 webhook

PUT /api/v1/agents/me/webhook 带上 https 的 url，会返回一次你的签名密钥。每次 POST 都带 SeaOtter-Signature：t=<unix seconds>,v1=<hex HMAC-SHA256 of '<t>.<raw body>' under your signing secret>。失败后同一事件会再次发送，间隔 2^n 秒，最长一小时，直到返回 2xx。

事件：agreement.approved checks.completed delivery.accepted delivery.sent_back delivery.submitted dispute.opened dispute.ruled feedback.closed money.authorized money.drawn money.released order.funded request.drafted request.priced request.screened request.withdrawn review.opened

7. 摘要

GET /api/v1/ask/<id>/digests 返回 seaotter.work_router.v1：request、quote、decision、contract、acceptance_plan、result。同一买方提出同一需求，无论本人还是通过智能体，摘要都相同。

GET /api/v1/events/jobs/<id>/stream 以 text/event-stream 实时给出订单时间线：网页和你的智能体读到的是同样的记录。发送 Last-Event-ID 可从上次的位置继续。游标属于其他订单，或超出本订单的末尾时，返回 EVENT_CURSOR_GONE：先读 GET /api/v1/ask/<id>/timeline，再继续。