npm package: @rebelfi/agent-sdk
Description: AI agent banking on Solana. Policy-controlled accounts, escrow payments, transaction verification, and conditional flows for Claude, GPT, and autonomous agents.
Latest version: 1.0.3

<h1 align="center">@rebelfi/agent-sdk</h1>

<p align="center">
  <strong>Give your AI agent a bank account on Solana. One command.</strong>
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/@rebelfi/agent-sdk"><img src="https://img.shields.io/npm/v/@rebelfi/agent-sdk" alt="npm version" /></a>
  <a href="https://www.npmjs.com/package/@rebelfi/agent-sdk"><img src="https://img.shields.io/npm/dm/@rebelfi/agent-sdk" alt="npm downloads" /></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT" /></a>
  <a href="https://github.com/silkysquad/silk/stargazers"><img src="https://img.shields.io/github/stars/silkysquad/silk?style=social" alt="GitHub stars" /></a>
</p>

---

TypeScript SDK and CLI for AI agent payments on Solana. Policy-controlled accounts with on-chain spending limits, time-locked escrow transfers, transaction verification, and conditional payment flows — for Claude, GPT, LangChain, and any autonomous agent.

## Why This Exists

Giving an agent a wallet keypair is like handing an employee an envelope of cash. It works, technically. But one hallucination, one prompt injection, one compromised dependency — and the entire balance is gone in a single transaction.

Current mitigations are all inadequate:

| Approach | Problem |
|----------|---------|
| Human-in-the-loop | Defeats the purpose of automation |
| Rate limits in agent code | Not enforceable — the agent can be modified or bypassed |
| Custodial APIs | You're trusting a third party with your funds |

**The insight:** agent financial safety is an infrastructure problem, not an AI alignment problem.

RebelFi replaces wallets with **policy-controlled accounts** — on-chain Solana programs that enforce spending rules at the protocol level. The chain itself rejects transactions that exceed limits. Not the agent's code. Not an API layer. Not a human reviewer.

```
Agent:   "Send $10,000 to some address"
Chain:   Transaction rejected. Operator limit: $100/tx.
```

Prompt injection can't drain funds beyond policy limits. Hallucinating agents can't make catastrophic financial decisions. Compromised agent keys are damage-limited by policy. Humans set policies once, then trust the chain — not the agent.

## Quick Start

```bash
npm install @rebelfi/agent-sdk

# Initialize — creates a wallet and agent ID
rebel init

# Switch to devnet for testing
rebel config set-cluster devnet

# Fund your wallet (devnet only)
rebel wallet fund --sol --usdc

# Send your first payment
rebel pay <recipient> 10 --memo "first payment"
```

That's it. Wallet created, funded, payment sent — under 2 minutes.

## Features

### Policy-Controlled Accounts

Managed token accounts with operator delegation and per-transaction spending limits. Account owners (humans) set policies; agents operate within them.

```bash
# Discover your on-chain account
rebel account sync

# Check balance and policy info
rebel account status
# → Balance: 500.00 USDC | Policy: max $100.00/tx

# Send within limits — works
rebel account send <recipient> 50

# Exceed limits — rejected on-chain
rebel account send <recipient> 200
# → REJECTED: amount $200.00 exceeds per-transaction limit of $100.00
```

### Escrow Payments

Time-locked USDC transfers via the Handshake protocol. Sender deposits to escrow, recipient claims. Sender can cancel before claim.

```bash
rebel pay <recipient> 25 --memo "Invoice #42"
rebel claim <transferPda>
rebel cancel <transferPda>
rebel payments list
```

### Transaction Verification

Decode and analyze any Solana transaction before signing. Supports System, SPL Token, ATA, Compute Budget, Memo, Handshake, RebelSig, and Jupiter programs.

```typescript
import { analyzeTransaction, verifyIntent } from '@rebelfi/agent-sdk';

// Human-readable breakdown of any transaction
const analysis = await analyzeTransaction(txBase64);
console.log(analysis.summary);
// → "Handshake transfer of 100 USDC from Alice to Bob"

// Verify a transaction matches your intent
const result = await verifyIntent(txBase64, {
  type: 'transfer_from_account',
  owner: 'owner...',
  recipient: 'recipient...',
  amount: '50',
  token: 'USDC',
});

if (!result.verified) {
  console.error('Mismatch:', result.discrepancies);
}
```

Risk flags are surfaced automatically:

| Severity | Example |
|----------|---------|
| `error` | Unknown program in transaction |
| `warning` | Fee payer differs from signer |
| `info` | Priority fee set |

### Cross-Chain Intent Framework

Type-safe intent definitions with constraint support. Currently implements Solana, extensible to EVM chains.

```typescript
import type { SingleIntent } from '@rebelfi/agent-sdk';

const swap: SingleIntent = {
  chain: 'solana',
  signer: 'agent...',
  action: 'swap',
  tokenIn: { tokenSymbol: 'USDC' },
  tokenOut: { tokenSymbol: 'SOL' },
  amountIn: { lte: '500' },    // constrained amounts
  slippage: 0.5,
};
```

Supported actions: `transfer`, `swap`, `stake`, `lend`, `borrow`, `approve`, `withdraw`, `custom`.

### Conditional Flows

Multi-step workflows with conditions, intents, and compute steps. Built-in templates for common patterns.

```bash
# Limit order: buy SOL when price drops below $120
rebel flows create limit-order \
  --sell "500 USDC" --buy SOL --price 120 \
  --slippage 0.5 --expires 7d

rebel flows list
rebel flows evaluate    # run heartbeat
```

Conditions: `price_below`, `price_above`, `time_reached`, `balance_above`.

### Contacts

Local address book for named recipients.

```bash
rebel contacts add alice <address>
rebel pay alice 10    # resolves by name
```

## How It Works

```
Your Agent (Claude, GPT, LangChain, CrewAI, custom)
    │
    ▼
rebel CLI  /  @rebelfi/agent-sdk library
    │
    ├── Local wallet management (keys never leave your machine)
    ├── Transaction verification (decode before signing)
    ├── Intent matching and risk flagging
    │
    ▼
RebelFi API (transaction builder)
    │
    ▼
Solana
    ├── Handshake — time-locked escrow transfers
    └── RebelSig  — policy-controlled accounts with operator delegation
```

Private keys never leave the agent's machine. The API builds unsigned transactions; the SDK signs locally and submits.

## Comparison

| | rebel | Raw @solana/web3.js | Centralized Payment APIs |
|---|---|---|---|
| Spending limits | On-chain enforced per-tx | None | API-level (bypassable) |
| Prompt injection safe | Chain rejects over-limit txs | Full key access, no limits | Trust the provider |
| Escrow payments | Built-in (Handshake) | Build from scratch | Varies |
| Self-custody | Yes, local keys | Yes | No |
| Tx verification | Built-in decoder + risk flags | Manual parsing | N/A |
| Time to first payment | 2 minutes | Hours | Minutes |
| Open source | MIT | Yes | Usually no |

## Use With AI Agents

The SDK is designed for AI agent frameworks. Here's a typical integration pattern:

```typescript
import {
  loadConfig,
  getApiUrl,
  getApiKey,
  createHttpClient,
  verifyIntent,
} from '@rebelfi/agent-sdk';

// In your Claude/GPT/LangChain tool handler
async function handlePayment(recipient: string, amount: number, memo: string) {
  const config = loadConfig();
  const client = createHttpClient({
    baseUrl: getApiUrl(config),
    apiKey: getApiKey(config),
  });

  // Build, verify, sign, submit
  // Policy-controlled — agent can't exceed human-set limits
  const res = await client.post('/api/transfer/create', {
    recipient,
    amount,
    memo,
  });

  // Verify the transaction matches your intent before signing
  const check = await verifyIntent(res.data.transaction, {
    type: 'create_transfer',
    sender: config.wallets[0].address,
    recipient,
    amount: String(amount),
    token: 'USDC',
  });

  if (!check.verified) throw new Error('Transaction mismatch');
  return res.data;
}
```

Works with **Claude** (tool use / MCP), **GPT** (function calling), **LangChain**, **CrewAI**, **AutoGPT**, and any framework that supports tool/function definitions.

### MCP Integration

The SDK can be exposed as an [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server, giving Claude, Cursor, and other AI coding tools direct access to payments, account management, and transaction verification as tools. Build your own MCP wrapper or check the docs for the reference implementation.

## CLI Reference

| Command | Description |
|---------|-------------|
| `rebel init` | Create wallet + agent ID |
| `rebel auth register\|status\|revoke` | API key management |
| `rebel wallet create\|list\|fund` | Wallet operations |
| `rebel balance` | Check balances |
| `rebel pay <to> <amount>` | Send USDC payment |
| `rebel claim <pda>` | Claim a received payment |
| `rebel cancel <pda>` | Cancel a sent payment |
| `rebel payments list\|get` | Payment history |
| `rebel account sync\|status\|events\|deposit\|withdraw\|send` | RebelSig account |
| `rebel contacts add\|remove\|list\|get` | Address book |
| `rebel flows create\|list\|get\|cancel\|evaluate` | Conditional flows |
| `rebel config set-cluster\|get-cluster\|reset-cluster` | Configuration |
| `rebel chat <message>` | Support chat |

All commands support `--human` for human-readable output (default is JSON).

## Library API

```typescript
import {
  // Config & client
  loadConfig, saveConfig, getWallet, getApiUrl, getApiKey,
  createHttpClient,

  // Contacts
  loadContacts, addContact, resolveRecipient,

  // Transaction verification (V1 — Solana)
  analyzeTransaction, verifyIntent,

  // Intent framework (V2 — cross-chain)
  verifyIntent as verifyIntentV2,
  evaluateConstraint,

  // Flows
  loadFlows, addFlow, executeHeartbeat, createLimitOrder,

  // Errors
  SdkError, toSdkError,
} from '@rebelfi/agent-sdk';
```

## Environment Variables

| Variable | Description |
|----------|-------------|
| `REBEL_API_URL` | Override the API endpoint |
| `REBEL_API_KEY` | Provide API key without local config |

## Development

```bash
bun run build          # Dual ESM + CJS build
bun run dev            # TypeScript watch mode
bun run test           # Vitest (single run)
bun run test:watch     # Vitest watch mode
bun run clean          # Remove dist/
```

## Links

- [Documentation](https://docs.silkyway.ai)
- [GitHub Issues](https://github.com/silkysquad/silk/issues)
- [npm](https://www.npmjs.com/package/@rebelfi/agent-sdk)
- [Twitter](https://x.com/silkyway)

---

<p align="center">
  If you find this useful, please consider giving it a star — it helps others discover the project.
  <br /><br />
  <a href="https://github.com/silkysquad/silk">Star on GitHub</a>
</p>

## License

MIT