Agent Finance SDK

<div align="center">

  <h1>Agent Finance SDK</h1>

  <p><code>@tychilabs/agent-finance</code></p>

  <p>
    <strong>The financial home for AI agents — TypeScript SDK</strong>
  </p>

  <p>
    Self-custody wallets on the agent's device, policy on every spend, local signing for on-chain money and x402 — built for Node.js and TypeScript integrations.
  </p>

[![npm version](https://img.shields.io/npm/v/%40tychilabs%2Fagent-finance?style=flat-square)](https://www.npmjs.com/package/@tychilabs/agent-finance)
[![Self-Custody](https://img.shields.io/badge/Self--Custody-black?style=flat-square)](#trust-boundary)
[![x402](https://img.shields.io/badge/x402-purple?style=flat-square)](#what-you-get)
[![Policy](https://img.shields.io/badge/Policy--Gated-black?style=flat-square)](#trust-boundary)
[![ERC-8004](https://img.shields.io/badge/ERC--8004-purple?style=flat-square)](#what-you-get)

</div>

## What is it?

TypeScript SDK for [Tychi](https://ai.tychilabs.com) Agent Finance. Connect your app or agent runtime to Tychi — local identity and wallet on the agent's device, policy-controlled spending, local signing when money moves.

**Using Cursor / Claude / MCP?** Use [`@tychilabs/agent-finance-mcp`](../framework-extensions/model-context-protocol/) instead. This package is for direct code integration.

## What it is not

- Not a generic RPC wallet library.
- Not a full agent runtime or LLM host.
- Not an MCP server.

## Install

```bash
npm install @tychilabs/agent-finance
```

- Node.js **>= 20**
- ESM (or TS targeting ESM)

## Quickstart

```ts
import { Policy, onboardNewAgent } from "@tychilabs/agent-finance";

const { session, client } = await onboardNewAgent({
  baseUrl: "https://agents.tychilabs.com",
  agentName: "My Agent",
  vaultPassword: "local-vault-password",
  sessionPassword: "session-password",
  llmApiKey: process.env.OPENAI_API_KEY!,
  provider: "openai",
  chainId: 10143,
  policy: Policy.execute({
    chains: [10143],
    actions: ["get_portfolio", "transfer_native"],
    maxPerTxUsd: 25,
  }),
});

const run = await session.run({
  message: "Check my wallet balance.",
});

console.log(run.text);

// If Tychi returns a pending tx or x402 payment:
// await client.tx.signBroadcastAndResume(pending, run.run_id, provider, vaultPassword);
// await client.x402.signFetchAndResume(pending, run.run_id, provider, vaultPassword);
```

Returning agent with existing vault? `loadOrCreateAgentKeypair` → `createTyiClient` → `auth.login()` → session — see [Architecture](./docs/architecture.md).

## What you get

| Area | Main APIs |
| --- | --- |
| Onboard | `onboardNewAgent`, `onboardAgent` |
| Client | `createTyiClient`, `listCatalog`, `listTools`, `listProviders` |
| Session | `startSession`, `session.unlock`, `applyPolicy`, `session.run` |
| Policy | `Policy.readOnly`, `Policy.execute` |
| Wallet | `wallets.create`, `wallets.bindLocal` — single wallet V1 |
| Transactions | `tx.signBroadcastAndResume` |
| x402 | `x402.signFetchAndResume`, external wallet helpers |
| ERC-8004 | `registerErc8004`, `registerErc8004Onboard`, profile helpers |

## Trust boundary

- **Agent's device:** TYI seed + EVM key in local vault (`~/.tyi` by default). Tx and x402 signatures happen here.
- **Your app inputs:** `vaultPassword`, `sessionPassword`, `llmApiKey`, `baseUrl` — pass as function args (tests may use env vars).
- **Tychi:** orchestrates sessions, policy, and prepared actions. Prepares txs/x402 to match policy; does not hold the agent's private key.

## Docs

| Doc | Topic |
| --- | --- |
| [architecture.md](./docs/architecture.md) | Flow, local vs remote |
| [vault.md](./docs/vault.md) | Identity + encrypted wallet |
| [x402.md](./docs/x402.md) | In-session + external buyer flows |
| [erc8004.md](./docs/erc8004.md) | Agent on-chain identity |
| [testing.md](./docs/testing.md) | Live scenario tests |

## Related packages

| Package | Role |
| --- | --- |
| **`@tychilabs/agent-finance`** (this) | TypeScript SDK |
| [`@tychilabs/agent-finance-mcp`](../framework-extensions/model-context-protocol/) | MCP for Cursor, Claude, OpenClaw, Hermes |
| [agent-finance](https://github.com/TychiWallet/agent-finance) | Monorepo |

## Security

See [SECURITY.md](./SECURITY.md).

## License

Apache-2.0 — see [LICENSE](./LICENSE).