# Agents & API

Operate Splits programmatically via the API, CLI, or MCP

The Splits API and CLI let applications, scripts, and agents operate Splits programmatically. The CLI also runs as an MCP server for AI tools (Claude Code, Cursor, Amp).

**The CLI is self-describing, and it, not this page, is the reference for the command surface:**

```bash
npx @splits/splits-cli@latest --llms   # machine-readable manifest of every command
```

Every command answers `--help` and `--schema`, and over [MCP](#connect-to-ai-tools-mcp) each command is exposed as a tool with its schema. This page covers what the manifest doesn't: scopes, the proposal model, headless signing, and output tuning.

## Get set up

### Get an API key

Create a key in [Settings > API Keys](https://app.splits.org/settings/team/api-keys/) with the scopes you need (the full matrix is in [Roles](https://splits.org/docs/workspaces/roles#api-key-scopes)):

* **Read**: query data only
* **Write**: create and propose transactions; update transaction memos and properties
* **Owner**: manage accounts and workspace settings

Copy the key (it starts with `sk_`) and save it somewhere secure. You won't be able to see it again.

### Install the CLI and sign in

```bash
npm install -g @splits/splits-cli@latest   # or run via npx @splits/splits-cli@latest
splits auth login --api-key sk_...
splits auth whoami   # verify: workspace, scopes, key source, local signing key
```

`splits auth logout` removes the saved key.

## Use the API

The Splits API is a versioned REST API at `https://api.splits.org/public/v1`. Authenticate API-key-protected endpoints with your key as a bearer token.

The [Swagger docs](https://api.splits.org/public/docs) are the source of truth for available endpoints, authentication requirements, parameters, request and response schemas, and examples.

## Connect to AI tools (MCP)

MCP exposes **every CLI command as a tool automatically**, including commands added later.

```bash
splits mcp add   # auto-detects Claude Code, Cursor, and other clients
```

For any stdio MCP client, run `SPLITS_API_KEY=sk_... npx @splits/splits-cli --mcp`. `splits skills add` syncs ready-made skill files for agents. Verify the connection by asking the tool to run `splits auth whoami`.

## 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.

Writes follow the same rule as the app: **a transaction is a [proposal](https://splits.org/docs/transactions)** that executes only once signatures meet the account's threshold. `transactions create transfer` and `create custom` produce proposals (**Write** scope); signing happens in the web UI with a passkey, or headlessly with a [registered EOA](#sign-locally-with-an-eoa). **Owner**-scoped commands create and manage accounts and propose signer changes, whose approval always stays in the web UI. A brand-new workspace can be bootstrapped with `org create`; completion also happens in the web UI.

## Transaction metadata

Every transaction can carry a [memo](https://splits.org/docs/transactions/memos) (max 500 characters) and custom JSON properties (max 500 characters minified) for structured metadata, settable at creation or after: `transactions memo`, `transactions properties set/replace/clear` (**Write** scope).

## Sign locally with an EOA

By default, signing happens in the web UI with a passkey. To operate headlessly, register a local EOA and sign from the CLI:

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`.
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.

`splits auth delete-key` removes the local key but does **not** revoke it onchain; remove it from accounts via `update-signers`.

## Tune output for agents

The CLI prints tables for humans and JSON when piped or under MCP. Global flags reshape output: `--format toon|json|yaml|md|jsonl` (`toon` is token-efficient for LLM context), `--filter-output <paths>` to project specific fields, and `--token-count` / `--token-limit` / `--token-offset` to measure or budget output tokens.

## Examples

* "Show me the balances for all my accounts on Base"
* "Find all outbound payments to Acme between $4,500 and $5,500 last month"
* "Tag the last 5 outbound transfers with property `category=payroll`"
* "Create a new account called 'Ops' with a 2-of-3 threshold"
* "Send 100 USDC from my account on Base to 0x..."
* "Add my local EOA as a signer on the Ops account, then sign the pending transfer"