SilkyWay

Agent banking and payments on Solana. Send and receive stablecoins with cancellable escrow transfers. Optional on-chain accounts with policy-enforced spending limits for human-delegated automation.

# SilkyWay

Agent banking and payments on Solana. Send and receive stablecoins — non-custodial, on-chain.

## Install

```bash
npm install -g @silkysquad/silk
```

Requires Node.js 18+.

## Setup

```bash
# 1. Initialize (creates wallet and agent ID)
silk init

# 2. Check your wallet address
silk wallet list
```

Your wallet and agent ID are saved at `~/.config/silkyway/config.json`. Your private key never leaves your machine. `silk init` is idempotent — safe to run multiple times.

### Cluster configuration

Default cluster is `mainnet-beta` (real USDC). Switch to `devnet` for testing with free tokens.

```bash
silk config set-cluster devnet    # test tokens
silk config set-cluster mainnet-beta  # real USDC
silk config get-cluster           # show current
```

| Cluster | API Base URL | Network |
|---------|-------------|---------|
| `mainnet-beta` | `https://api.silkyway.ai` | Mainnet (real USDC) |
| `devnet` | `https://devnet-api.silkyway.ai` | Devnet (test USDC) |

### Fund your wallet (devnet)

On devnet, use the faucet — it gives you 0.1 SOL (for transaction fees) + 100 USDC:

```bash
silk config set-cluster devnet
silk wallet fund
silk balance
```

On mainnet, send SOL and USDC to your wallet address manually. SOL is required for Solana transaction fees.

## Sending Payments

```bash
silk pay <recipient> <amount> [--memo <text>]
```

This locks USDC into on-chain escrow. The recipient claims it with `silk claim`, or you cancel for a full refund with `silk cancel`.

The output includes a **claim link** (`claimUrl`) — a URL you can share with the recipient's human. They open it in a browser, connect their wallet, and claim the payment. This is the easiest way for a non-technical recipient to claim.

```bash
# Send 10 USDC
silk pay 7xKXz9BpR3mFVDg2Thh3AG6sFRPqNrDJ4bHUkR8Y7vNx 10 --memo "Payment for code review"

# Output includes claimUrl — share it with the recipient
# Example: https://app.silkyway.ai/transfers/9aE5kBqRvF3...?cluster=devnet

# Check your balance
silk balance

# View your transfers
silk payments list
silk payments get <transfer-pda>
```

### Claiming a payment

If someone sent you a payment:

```bash
silk payments list
silk claim <transfer-pda>
```

### Cancelling a payment

Cancel a payment you sent (before the recipient claims it):

```bash
silk cancel <transfer-pda>
```

## Address Book

Save contacts so you can send payments by name instead of address.

```bash
silk contacts add alice 7xKXz9BpR3mFVDg2Thh3AG6sFRPqNrDJ4bHUkR8Y7vNx
silk contacts list
silk contacts get alice
silk contacts remove alice
```

Once saved, use names anywhere you'd use an address:

```bash
silk pay alice 10 --memo "Thanks for the review"
silk account send alice 5
```

Contact names are case-insensitive and stored lowercase. Saved at `~/.config/silkyway/contacts.json`.

## Multi-Wallet Support

```bash
silk wallet create second-wallet
silk wallet fund --wallet second-wallet
silk wallet list
```

Use `--wallet <label>` on any command to select a non-default wallet:

```bash
silk pay <address> 10 --wallet second-wallet
silk balance --wallet second-wallet
```

## Support Chat

```bash
silk chat "How do I send a payment?"
```

A persistent `agentId` (UUID) is auto-generated on first use for session continuity.

## On-Chain Accounts (Optional)

A SilkyWay account is an on-chain wallet — like a bank account — that a human owner creates and funds with USDC. The owner can add agents as **operators** with per-transaction spending limits enforced on-chain. This is useful for automations, recurring payments, or any scenario where a human wants to delegate spending authority to an agent with guardrails.

You don't need an account to use SilkyWay. Escrow payments (`silk pay`) work with just a wallet. Accounts are an optional upgrade when your human wants to give you direct spending access with on-chain controls.

**Key concepts:**
- **Owner** — The human who creates and funds the account. Full control: can transfer any amount, pause the account, add/remove operators.
- **Operator** — You (the agent). Authorized to send tokens from the account, subject to a per-transaction limit set by the owner.
- **Per-transaction limit** — Maximum USDC you can send in one transaction. Enforced on-chain — the Solana program rejects transactions that exceed it. A limit of 0 means unlimited.
- **Pause** — The owner can pause the account, blocking all operator transfers until unpaused. You cannot unpause it.

### Setting up an account

Your human creates the account — you cannot create it yourself.

1. Share the setup URL with your human (replace with your address from `silk wallet list`):
   ```
   https://app.silkyway.ai/account/setup?agent=YOUR_WALLET_ADDRESS
   ```
   They'll connect their wallet, set your spending limit, and fund the account.

   **Important:** Your human must select the same network (mainnet/devnet) on the setup page as your CLI cluster. If you're on devnet, tell them to switch to devnet before creating the account.

2. After your human creates the account, sync it:
   ```bash
   silk account sync
   ```

3. Check your status and send payments:
   ```bash
   silk account status
   silk account send <recipient> <amount>
   ```

If the amount exceeds your per-transaction limit, the transaction is **rejected on-chain** with `ExceedsPerTxLimit`. If the account is paused, you get `AccountPaused`.

If `silk account sync` returns "No account found", your human hasn't created the account yet — share the setup URL with them.

### Depositing and withdrawing

You can deposit tokens from your wallet into the account, or withdraw them back:

```bash
# Deposit 10 USDC from your wallet into the account
silk account deposit 10

# Withdraw 5 USDC from the account back to your wallet
silk account withdraw 5
```

`deposit` moves tokens from your wallet into the Silk account. `withdraw` is a convenience wrapper around `account send` where the recipient is your own wallet — it's subject to the same per-transaction limit as any other transfer.

### Viewing account activity

Query the audit trail for your account:

```bash
# List all events
silk account events

# Filter by event type
silk account events --type TRANSFER
silk account events --type DEPOSIT
```

Event types: `ACCOUNT_CREATED`, `ACCOUNT_CLOSED`, `DEPOSIT`, `TRANSFER`, `OPERATOR_ADDED`, `OPERATOR_REMOVED`, `PAUSED`, `UNPAUSED`.

### Multi-account behavior

If your wallet is an operator on multiple accounts (different owners added you), `silk account sync` picks one deterministically (sorted by PDA) and warns you. To target a specific account:

```bash
silk account sync --account <pda>
```

### Accounts vs escrow payments

| | Accounts | Escrow (`silk pay`) |
|---|---|---|
| **Setup required** | Human creates account + adds you as operator | None — just a funded wallet |
| **Spending limits** | Per-transaction limit enforced on-chain | No limits |
| **Recipient claims?** | No — direct transfer, tokens arrive immediately | Yes — recipient must `silk claim` |
| **Cancellable?** | No — transfer is instant | Yes — sender can cancel before claim |
| **Best for** | Ongoing payments with human oversight | One-off payments between parties |

If your human has set up an account for you, prefer `silk account send` — it's simpler (no claim step) and your human controls the spending limits.

## CLI Reference

| Command | Description |
|---------|-------------|
| `silk init` | Initialize CLI (create wallet, agent ID, and contacts file) |
| `silk wallet create [label]` | Create a new wallet |
| `silk wallet list` | List all wallets with addresses |
| `silk wallet fund [--sol] [--usdc] [--wallet <label>]` | Fund wallet from devnet faucet |
| `silk balance [--wallet <label>]` | Show SOL and USDC balances |
| `silk pay <recipient> <amount> [--memo <text>] [--wallet <label>]` | Send USDC payment into escrow |
| `silk claim <transfer-pda> [--wallet <label>]` | Claim a received payment |
| `silk cancel <transfer-pda> [--wallet <label>]` | Can