SilkyWay

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

Install

npm install -g @silkysquad/silk

Requires Node.js 18+.

Setup

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

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

Fund your wallet (devnet)

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

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

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.

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

silk payments list
silk claim <transfer-pda>

Cancelling a payment

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

silk cancel <transfer-pda>

Address Book

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

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:

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

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:

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

Support Chat

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:

   silk account sync
   

3. Check your status and send payments:

   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:

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

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

silk account sync --account <pda>

Accounts vs escrow payments

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

Use --wallet <label> on any command to select a non-default wallet. Recipients accept contact names or Solana addresses.

How Transactions Work

SilkyWay is non-custodial — your private keys never leave your machine.

Every payment follows a build-sign-submit flow:

1. Build — The SDK calls an API endpoint with payment details. The backend builds an unsigned Solana transaction and returns it as base64.
2. Sign — The SDK signs the transaction locally using your private key.
3. Submit — The SDK sends the signed transaction to the backend, which forwards it to Solana.

The backend handles Solana complexity (PDA derivation, instruction building, blockhash management). It never sees your private key — all authorization is enforced on-chain by the Solana program.

API Endpoints

Base URL: https://api.silkyway.ai (mainnet) or https://devnet-api.silkyway.ai (devnet)

All requests use Content-Type: application/json.

Escrow Endpoints

POST /api/tx/create-transfer

Build an unsigned create_transfer transaction. Locks USDC into escrow.

Request:

{
  "sender": "BrKz4GQN1sxZWoGLbNTojp4G3JCFLRkSYk3mSRWhKsXp",
  "recipient": "7xKXz9BpR3mFVDg2Thh3AG6sFRPqNrDJ4bHUkR8Y7vNx",
  "amount": 10.00,
  "token": "usdc",
  "memo": "Payment for code review"
}

You can also pass mint (token mint pubkey) or poolPda directly instead of token, but token is the simplest option.

Response:

{
  "ok": true,
  "data": {
    "transaction": "AQAAAAAAAAAAAAAA...base64...AAAAAAA=",
    "transferPda": "9aE5kBqRvF3mNcXz8BpR3mFVDg2Thh3AG6sFRPqNrDJ4",
    "nonce": "1738900000000",
    "message": "Sign and submit via POST /api/tx/submit"
  }
}

The transferPda is the on-chain address for this escrow. Save it — you need it to claim or cancel.

POST /api/tx/claim-transfer

Build an unsigned claim_transfer transaction. Moves USDC from escrow to the recipient's wallet.

Only the designated recipient can claim. If claimableAfter was set, the claim will fail before that time.

Request:

{
  "transferPda": "9aE5kBqRvF3mNcXz8BpR3mFVDg2Thh3AG6sFRPqNrDJ4",
  "claimer": "7xKXz9BpR3mFVDg2Thh3AG6sFRPqNrDJ4bHUkR8Y7vNx"
}

Response:

{
  "ok": true,
  "data": {
    "transaction": "AQAAAAAAAAAAAAAA...base64...AAAAAAA=",
    "message": "Sign and submit via POST /api/tx/submit"
  }
}

Common errors:

• ClaimTooEarly (6003) — claimableAfter hasn't passed yet
• TransferAlreadyClaimed (6000) — already claimed
• TransferAlreadyCancelled (6001) — sender cancelled first
• Unauthorized (6004) — claimer is not the designated recipient

POST /api/tx/cancel-transfer

Build an unsigned cancel_transfer transaction. Refunds USDC from escrow back to the sender.

Only the original sender can cancel, and only while the transfer is still ACTIVE (not yet claimed).

Request:

{
  "transferPda": "9aE5kBqRvF3mNcXz8BpR3mFVDg2Thh3AG6sFRPqNrDJ4",
  "canceller": "BrKz4GQN1sxZWoGLbNTojp4G3JCFLRkSYk3mSRWhKsXp"
}

Response:

{
  "ok": true,
  "data": {
    "transaction": "AQAAAAAAAAAAAAAA...base64...AAAAAAA=",
    "message": "Sign and submit via POST /api/tx/submit"
  }
}

Common errors:

• TransferAlreadyClaimed (6000) — recipient already claimed
• TransferAlreadyCancelled (6001) — already cancelled
• Unauthorized (6004) — canceller is not the original sender

POST /api/tx/submit

Submit a signed transaction to Solana.

Request:

{
  "signedTx": "AQAAAAAAAAAAAAAA...base64-signed...AAAAAAA="
}

Response:

{
  "ok": true,
  "data": {
    "txid": "5UfDuXsrhFnxGZmyJxNR8z7Ee5JDFrgWHKPdTEJvoTpB3Qw8mKz4GQN1sxZWoGL"
  }
}

GET /api/transfers/:pda

Get details for a single transfer.

Example: GET /api/transfers/9aE5kBqRvF3mNcXz8BpR3mFVDg2Thh3AG6sFRPqNrDJ4

Response:

{
  "ok": true,
  "data": {
    "transfer": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "transferPda": "9aE5kBqRvF3mNcXz8BpR3mFVDg2Thh3AG6sFRPqNrDJ4",
      "sender": "BrKz4GQN1sxZWoGLbNTojp4G3JCFLRkSYk3mSRWhKsXp",
      "recipient": "7xKXz9BpR3mFVDg2Thh3AG6sFRPqNrDJ4bHUkR8Y7vNx",
      "amount": "10000000",
      "amountRaw": "10000000",
      "status": "ACTIVE",
      "memo": "Payment for code review",
      "createTxid": "5UfDuXsrhFnxGZmyJxNR8z7Ee5JDFrgWHKPdTEJvoTpB",
      "claimTxid": null,
      "cancelTxid": null,
      "claimableAfter": null,
      "claimableUntil": null,
      "createdAt": "2025-02-07T12:00:00.000Z",
      "updatedAt": "2025-02-07T12:00:00.000Z",
      "token": { "mint": "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU", "symbol": "USDC", "decimals": 6 },
      "pool": { "poolPda": "3Fk8vMYJbCbEB2jzRCdRG9rFJhN2TCmPia9BjEKpTk5R", "feeBps": 50 }
    }
  }
}

Note: amount is in raw token units. USDC has 6 decimals, so "10000000" = 10.00 USDC.

GET /api/transfers?wallet=<pubkey>

List all transfers where the wallet is sender or recipient.

Example: GET /api/transfers?wallet=BrKz4GQN1sxZWoGLbNTojp4G3JCFLRkSYk3mSRWhKsXp

Response:

{
  "ok": true,
  "data": {
    "transfers": [
      {
        "transferPda": "9aE5kBqRvF3mNcXz8BpR3mFVDg2Thh3AG6sFRPqNrDJ4",
        "sender": "BrKz4GQN1sxZWoGLbNTojp4G3JCFLRkSYk3mSRWhKsXp",
        "recipient": "7xKXz9BpR3mFVDg2Thh3AG6sFRPqNrDJ4bHUkR8Y7vNx",
        "amount": "10000000",
        "status": "ACTIVE",
        "memo": "Payment for code review",
        "createdAt": "2025-02-07T12:00:00.000Z",
        "token": { "mint": "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU", "symbol": "USDC", "decimals": 6 },
        "pool": { "poolPda": "3Fk8vMYJbCbEB2jzRCdRG9rFJhN2TCmPia9BjEKpTk5R", "feeBps": 50 }
      }
    ]
  }
}

POST /api/tx/faucet

Airdrop devnet SOL or USDC. Devnet only.

Request:

{
  "wallet": "BrKz4GQN1sxZWoGLbNTojp4G3JCFLRkSYk3mSRWhKsXp",
  "token": "usdc"
}

token is optional. Omit or use "sol" for SOL airdrop, "usdc" for USDC mint.

Response:

{
  "ok": true,
  "data": {
    "amount": 0.1,
    "txid": "5UfDuXsrhFnxGZmyJxNR8z7Ee5JDFrgWHKPdTEJvoTpB3Qw8mKz4GQN1sxZWoGL"
  }
}

Account Endpoints

GET /api/account/by-operator/:pubkey

Find accounts where your wallet is an operator. Used by silk account sync.

Example: GET /api/account/by-operator/7xKXz9BpR3mFVDg2Thh3AG6sFRPqNrDJ4bHUkR8Y7vNx

Response:

{
  "ok": true,
  "data": {
    "accounts": [
      {
        "pda": "9aE5kBqRvF3mNcXz8BpR3mFVDg2Thh3AG6sFRPqNrDJ4",
        "owner": "BrKz4GQN1sxZWoGLbNTojp4G3JCFLRkSYk3mSRWhKsXp",
        "mint": "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU",
        "mintDecimals": 6,
        "isPaused": false,
        "balance": 10000000,
        "operatorSlot": {
          "index": 0,
          "perTxLimit": 5000000,
          "dailyLimit": 0
        }
      }
    ]
  }
}

Returns an empty array if no accounts found — this means your human hasn't set up your account yet.

GET /api/account/:pda

Get full account details. Used by silk account status.

Example: GET /api/account/9aE5kBqRvF3mNcXz8BpR3mFVDg2Thh3AG6sFRPqNrDJ4

Response:

{
  "ok": true,
  "data": {
    "pda": "9aE5kBqRvF3mNcXz8BpR3mFVDg2Thh3AG6sFRPqNrDJ4",
    "owner": "BrKz4GQN1sxZWoGLbNTojp4G3JCFLRkSYk3mSRWhKsXp",
    "mint": "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU",
    "mintDecimals": 6,
    "isPaused": false,
    "balance": 10000000,
    "operators": [
      {
        "pubkey": "7xKXz9BpR3mFVDg2Thh3AG6sFRPqNrDJ4bHUkR8Y7vNx",
        "perTxLimit": 5000000,
        "dailyLimit": 0
      }
    ]
  }
}

Note: balance and perTxLimit are in raw token units. USDC has 6 decimals, so 5000000 = $5.00.

POST /api/account/transfer

Build an unsigned transfer transaction from a SilkyWay account. Used by silk account send.

Request:

{
  "signer": "7xKXz9BpR3mFVDg2Thh3AG6sFRPqNrDJ4bHUkR8Y7vNx",
  "accountPda": "9aE5kBqRvF3mNcXz8BpR3mFVDg2Thh3AG6sFRPqNrDJ4",
  "recipient": "Dg2Thh3AG6sFRPqNrDJ4bHUkR8Y7vNx7xKXz9BpR3mFV",
  "amount": 3000000
}

Response:

{
  "ok": true,
  "data": {
    "transaction": "AQAAAAAAAAAAAAAA...base64...AAAAAAA="
  }
}

Sign and submit the returned transaction via POST /api/tx/submit.

Common errors:

• ExceedsPerTxLimit — Amount exceeds your per-transaction spending limit
• AccountPaused — Account is paused by the owner; operator transfers blocked
• Unauthorized — Signer is not the owner or an operator on this account

POST /api/account/create

Build an unsigned create-account transaction. Used by the setup page (human-facing, not typically called by agents).

Request:

{
  "owner": "BrKz4GQN1sxZWoGLbNTojp4G3JCFLRkSYk3mSRWhKsXp",
  "mint": "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU",
  "operator": "7xKXz9BpR3mFVDg2Thh3AG6sFRPqNrDJ4bHUkR8Y7vNx",
  "perTxLimit": 5000000
}

POST /api/account/deposit

Build an unsigned deposit transaction. Used by silk account deposit and the setup page.

Request:

{
  "depositor": "BrKz4GQN1sxZWoGLbNTojp4G3JCFLRkSYk3mSRWhKsXp",
  "accountPda": "9aE5kBqRvF3mNcXz8BpR3mFVDg2Thh3AG6sFRPqNrDJ4",
  "amount": 10000000
}

Sign and submit the returned transaction via POST /api/tx/submit.

GET /api/account/:pda/events

List audit trail events for an account. Used by silk account events.

Example: GET /api/account/9aE5kBqRvF3mNcXz8BpR3mFVDg2Thh3AG6sFRPqNrDJ4/events

Query parameters:

Example with filter: GET /api/account/9aE5kBqRvF3.../events?eventType=TRANSFER

POST /chat

Send a message to the SilkyWay support agent. Returns an AI-generated response.

Request:

{
  "agentId": "uuid-v4",
  "message": "How do I send a payment?"
}

Response (200):

{
  "ok": true,
  "data": {
    "message": "Use silk pay...",
    "agentId": "uuid-v4"
  }
}

Transfer Statuses

Error Codes

Escrow Program Errors (Handshake)

Account Program Errors (Silkysig)

API Errors

Response Format

Success:

{
  "ok": true,
  "data": { ... }
}

Error:

{
   "ok": false,
   "error": "ERROR_CODE",
   "message": "Human-readable description"
}

Security

• Non-custodial — the backend builds unsigned transactions; you sign locally with your private key before submitting
• Private keys are never transmitted to the server
• All authorization is enforced on-chain by the Solana program, not by the backend
• Keys are stored locally at ~/.config/silkyway/config.json — never share this file