PE-9413: Update agent API docs by juliogarciag · Pull Request #67 · 0xSplits/splits-docs

juliogarciag · 2026-10-22T19:54:08Z

Description

Documents what the Agent API expansions project shipped: the browser login, agents as workspace members, workspaces created from an agent, and the proposal kinds and commands the CLI gained. Merge after @splits/splits-cli 0.5.0 is published (0xSplits/splits-cli#62): the pages describe automations create, accounts sign-message, workspace create-agent-owned, and the agent member behavior, which 0.4.0 does not have.

Changes made

One home per fact, and every surface page points at its commands

introduction/agents.mdx is rewritten around how an agent gets access and what it is in the workspace: browser login (auth login --client-name, and login-start / login-status under MCP), the API key path, several saved workspaces, scopes (now with the role rule: Owner-only operations need the key's member to be an Owner), the proposal kinds, dataType on transactions, headless signing of signer and network changes, sign-message, and feedback send. The mcp add / skills add instructions are unchanged.
CLAUDE.md's canonical-homes table names the new homes: browser login on /introduction/agents, agent members on /members, workspaces created from an agent on /workspaces.

An agent is a member, and the approver sets its role

members/index.mdx: new "Agent members" section (what it is, no email or login, EOA keys only, role set at approval, cannot be invited, removal proposes dropping its keys from every account). members list now documents kind.
workspaces/roles.mdx: API keys are created in Settings or granted at a browser login; a key acts as a member; granting owner at login makes the agent an Owner.
introduction/core-concepts.mdx and members/keys.mdx: a member can be an agent; an EOA is registered under the member whose key registers it.

A workspace can be created from an agent

workspaces/index.mdx: new "From an agent" section with the two paths (workspace create, approved in the browser, and workspace create-agent-owned, owned by the agent with an unverified recovery email) and what differs from the app flow (agent key on the Treasury, email signer on the Root), plus a Programmatic access section.

Each surface lists its new commands under Programmatic access

transactions/index.mdx: every transactions create kind, update-gas-estimation, and signing of signer/network changes.
transactions/sends.mdx: --source-token / --source-chain-id ("Pay with"), off-ramps as sends to a bank.
transactions/swaps.mdx: transactions create swap replaces "no dedicated swap command", with cross-network and slippage flags.
accounts/earn.mdx: new section: the earn object on balances, earn-deposit / earn-withdraw, settings get auto-earn state, auto-earn-on / auto-earn-off.
banking/offramping.mdx: new section: offramp external-accounts and transactions create offramp (amount is what the bank receives, fee added on top, Owner key of a verified workspace).
invoicing/index.mdx and invoicing/recurring.mdx: invoices list / get / create, the Pro plan requirement, and schedules through --interval / --due-date-days (carried over from the closed Document the invoice CLI commands (PE-9117) #63).
accounts/index.mdx: automations create; accounts/editing.mdx and accounts/signers.mdx: signer changes are signable by an EOA, and an agent member may add only its own keys.
introduction/networks-and-assets.mdx: accounts networks / add-networks / remove-networks.
integrations/walletconnect.mdx: new section for accounts sign-message.
contacts/index.mdx: send rules come back on list and lookup.

Solutions and integrations follow

solutions/ai-agents.mdx: the agent is a member of its own; setup starts with the browser login instead of an API key; the "no programmatic route to a key" limit is replaced. business-banking, revenue-automation, and family-wallet drop invoices, off-ramps, and automations from their web-only lines. integrations/bankr.mdx step 1 offers the browser login.

How has this been tested?

pnpm lint:prose (strict STE on src/pages/solutions), node scripts/check-prose.mjs on every changed page, and pnpm build (internal links) pass; an inbound-anchor grep for the two removed /introduction/agents anchors found and fixed the one stale link.
Every command, flag, scope, and role claim was checked against splits-cli src/cli.ts on main and the public v1 routes on splits master; the consent-page and Members-page claims against splits-teams master.
Read the .md twin of /introduction/agents from the build output.

Other notes

Linear: PE-9413. Supersedes Document the invoice CLI commands (PE-9117) #63 (closed), whose invoice text is folded in here.
Not changed, flagged: transactions/swaps.mdx still says Splits charges no swap fees. 0xSplits/splits#3870 applies plan swap rates from 2026-11-09, which is a different project's docs update.

🤖 Generated with Claude Code

Agents & API now covers the browser login, agent members, agent-created workspaces, the scope-and-role rule, and the proposal kinds the CLI gained. Each surface page lists its new commands under Programmatic access: swaps, Earn, auto-earn, off-ramps, invoices, automations, networks, message signing, and contact send rules. Members gains an Agent members section and Workspaces a From an agent section; Roles explains that an owner scope granted at login makes the agent an Owner. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

vercel · 2026-10-22T19:54:11Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
splits-docs	Ready	Preview	Oct 23, 2026 7:17pm UTC

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

juliogarciag · 2026-10-23T00:24:01Z

@zherring Made a bunch of updates to the docs. I already taken a look at the docs changes in the preview app.

zherring · 2026-10-23T14:47:13Z

+
+## Agent members
+
+An **agent member** is an AI agent that joined the workspace when a member approved its [browser login](/introduction/agents#sign-in-from-the-browser), or by [creating the workspace](/workspaces#from-an-agent) itself. It is a member of its own, not the person who approved it: [Settings > Members](https://app.splits.org/settings/team/members/) shows it with an *Agent* label, and its proposals, signatures, signer registrations, and invoices are recorded under its name. One agent member exists per agent signing key, reused in every workspace that key is approved in; its display name is the client name the agent gave at its first login.


@juliogarciag is this worth pointing out? Seems like its just updating from our prev permissions, which doesn't seem like its' appropriate to include in the body? wdyt?

Yeah, I think it's better to cut the "It is a member..." part. What about this?

An agent member is an AI agent that joined the workspace when a member approved its sign-in, or by creating the workspace itself. Settings > Members shows it with an Agent label, and its activity is recorded under its name. One agent member exists per agent signing key, in every workspace that key is approved in, named after the client name the agent gave at its first sign-in.

muuuuch more clear, ty

zherring · 2026-10-23T14:47:13Z

 - **Recovery is contract-enforced.** The Treasury owns the account, so the Treasury's signers can remove the agent's key by [resetting signers](/accounts/editing#resetting-signers). The reset needs no signature from the account's own signers and does not change the account's address. Deposits and integrations that point at the address keep working.
 - **Scopes bound the API, signers bound the chain.** The agent's API key carries a [scope](/workspaces/roles#api-key-scopes) (Read, Write, or Owner). The scope governs what the agent can query and propose. Scopes grant **no onchain signing authority**. Only the agent's registered key on the account's signer set grants that authority.
 - **Every action is a proposal.** The agent proposes [transactions](/transactions) like any client. A transaction executes when its signatures meet the threshold. The agent proposes signer changes, and a human approves them in the app.
+- **The agent is a member of its own.** When you approve the agent's [browser login](/introduction/agents#sign-in-from-the-browser), it joins the workspace as an [agent member](/members#agent-members) with its own name and key. The workspace records its actions under its name, not yours.


of its own what?

Deleting the on its own part. Doesn't add a lot. I think the ideas was to say it was a member on its own right (instead of being tied to an existing user).

zherring · 2026-10-23T14:47:14Z

 ### Sign the agent in

-The agent [signs in to the CLI](/introduction/agents#install-the-cli-and-sign-in) with the API key. The agent then confirms the workspace, scopes, and key source.
+The agent starts a [browser login](/introduction/agents#sign-in-from-the-browser) and shows you a link and a code. You sign in, enter the code, and connect the workspace with the [scopes](/workspaces/roles#api-key-scopes) you choose. No API key passes through the agent. The agent then confirms the workspace, scopes, and key source.


this is kind of disconnected. a link and a code .. how do you sign in with a link and a code? do you click the link? would be explicit here.

The agent opens the link automatically and the user only has to paste the code. What about this?

The agent starts a browser login and gives you a code. A Splits login page opens. Sign in, enter the code, and connect the workspace with the scopes you choose.

zherring · 2026-10-23T14:47:15Z

-2. `splits accounts update-signers <account> --addEoaSignerIds ... --threshold N`: propose adding it as a signer (**Owner** scope). A human approves the proposal in the web UI, and the update applies to every active network.
-3. `splits transactions sign <id>`: sign pending proposals with the local key (**Write** scope). Auto-submits once the threshold is met.
+1. `splits auth create-key --register`: generate a local EOA (stored in `~/.splits/config.json`) and register it. Import an existing key instead with `echo $PRIVATE_KEY | splits auth import-key`. `splits auth whoami` lists the local keys and whether each is registered.
+2. `splits accounts update-signers <account> --add-eoa-signer-ids <id> --threshold N`: propose adding it as a signer (**Owner** scope). An agent member can propose adding its own keys, with no other change, and an Owner signs it. A workspace [created from an agent](/workspaces#from-an-agent) already has the agent's key as the Treasury's only signer.


what does this "with no other change" mean? kinda unclear in isolation?

Not editing the threshold. Yeah, doesn't make a lot of sense to point it out. Removing those words.

zherring · 2026-10-23T14:47:15Z

 ## The model

-Everything visible in the app is queryable with the **Read** scope: accounts, balances, transactions (filterable by account, direction, amount, date, and memo), contacts, tokens, networks, members, settings, and automations.
+Everything visible in the app is queryable with the **Read** scope: accounts, balances (including [Earn](/accounts/earn#programmatic-access) positions), transactions (filterable by account, direction, amount, date, and memo), contacts with their send rules, tokens, networks, members, settings, automations, and invoices. Bank accounts need the **Owner** scope.


"Transferring to and from bank accounts require…"

zherring · 2026-10-23T14:47:16Z

+- `splits transactions create swap --account 0x... --chain-id 8453 --sell-token 0x... --buy-token 0x... --amount 0.5`: propose a swap that sells an exact amount (**Write** scope)
+- `splits transactions create swap ... --destination-chain-id 1`: swap onto another network (**Write** scope)
+
+A just-in-time swap inside a send is a transfer with `--source-token`; see [Sends](/transactions/sends#programmatic-access).


this is confusing to me? better way to phrase it?

something like, agents can swap-and-send in a single transaction, by setting a transfer's --source token and payment source as different" or something equiv?

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

…api-docs # Conflicts: # CLAUDE.md

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

juliogarciag · 2026-10-23T19:23:18Z

@zherring Addressed your comments. Can you check again?

zherring · 2026-10-23T19:30:29Z

all of it? 🫠 ok

zherring

skimmed everything, reviewed replies, lgtm for now! ty for refactoring the docs w/ all the agent changes

zherring · 2026-10-23T20:02:01Z

done. appreciate it julio!

juliogarciag and others added 2 commits October 22, 2026 14:44

Name both scopes an off-ramp needs and keep the role rule on Roles

be11fba

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

vercel Bot deployed to Preview October 22, 2026 19:55

View deployment

juliogarciag and others added 2 commits October 22, 2026 18:02

Trim the new Programmatic access bullets to one line each

fef41a0

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Shorten the sign-message bullet

df1c1ba

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

vercel Bot deployed to Preview October 22, 2026 23:04

View deployment

Drop the production-only line from agent setup

adaeae0

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

vercel Bot deployed to Preview October 22, 2026 23:32

View deployment

juliogarciag requested review from abramdawson, r0ohafza and zherring and removed request for abramdawson October 22, 2026 23:50

juliogarciag marked this pull request as ready for review October 22, 2026 23:50

zherring reviewed Oct 23, 2026

View reviewed changes

Apply Zach's review: plainer agent member and sign-in wording

db07578

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

vercel Bot deployed to Preview October 23, 2026 19:01

View deployment

Merge remote-tracking branch 'origin/main' into pe-9413-update-agent-…

589bf11

…api-docs # Conflicts: # CLAUDE.md

vercel Bot deployed to Preview October 23, 2026 19:11

View deployment

Drop the production-only line again

c93e215

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

vercel Bot deployed to Preview October 23, 2026 19:17

View deployment

juliogarciag requested a review from zherring October 23, 2026 19:23

zherring approved these changes Oct 23, 2026

View reviewed changes

juliogarciag merged commit e68ae36 into main Oct 23, 2026
6 of 9 checks passed

juliogarciag deleted the pe-9413-update-agent-api-docs branch October 23, 2026 19:47


		## Agent members

		An agent member is an AI agent that joined the workspace when a member approved its [browser login](/introduction/agents#sign-in-from-the-browser), or by [creating the workspace](/workspaces#from-an-agent) itself. It is a member of its own, not the person who approved it: [Settings > Members](https://app.splits.org/settings/team/members/) shows it with an Agent label, and its proposals, signatures, signer registrations, and invoices are recorded under its name. One agent member exists per agent signing key, reused in every workspace that key is approved in; its display name is the client name the agent gave at its first login.

Conversation

juliogarciag commented Oct 22, 2026

Description

Changes made

How has this been tested?

Other notes

Uh oh!

vercel Bot commented Oct 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

juliogarciag commented Oct 23, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

juliogarciag commented Oct 23, 2026

Uh oh!

zherring commented Oct 23, 2026

Uh oh!

zherring left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

zherring commented Oct 23, 2026

Uh oh!

This branch was successfully deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

vercel Bot commented Oct 22, 2026 •

edited

Loading