SilkyWay

Use --wallet 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"
}

| Field | Type | Required | Description | |-------|------|----------|-------------| | sender | string | yes | Sender's Solana public key | | recipient | string | yes | Recipient's Solana public key | | amount | number | yes | Amount in token units (e.g. 10.00 = 10 USDC) | | token | string | yes | Token symbol (e.g. "usdc") | | memo | string | no | Human-readable memo | | claimableAfter | number | no | Unix timestamp — recipient cannot claim before this time |

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"
}

| Field | Type | Required | Description | |-------|------|----------|-------------| | transferPda | string | yes | The transfer's on-chain PDA | | claimer | string | yes | Recipient's Solana public key |

Response:

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

Common errors:

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"
}

| Field | Type | Required | Description | |-------|------|----------|-------------| | transferPda | string | yes | The transfer's on-chain PDA | | canceller | string | yes | Sender's Solana public key |

Response:

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

Common errors:

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=\

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
}

| Field | Type | Required | Description | |-------|------|----------|-------------| | signer | string | yes | Your wallet address (operator) | | accountPda | string | yes | The account's on-chain PDA | | recipient | string | yes | Recipient's Solana public key | | amount | number | yes | Amount in raw token units (e.g. 3000000 = 3.00 USDC) |

Response:

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

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

Common errors:

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

| Field | Type | Required | Description | |-------|------|----------|-------------| | depositor | string | yes | Wallet address depositing the tokens | | accountPda | string | yes | The account's on-chain PDA | | amount | number | yes | Amount in raw token units (e.g. 10000000 = 10.00 USDC) |

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:

| Param | Type | Required | Description | |-------|------|----------|-------------| | eventType | string | no | Filter by event type: ACCOUNT_CREATED, ACCOUNT_CLOSED, DEPOSIT, TRANSFER, OPERATOR_ADDED, OPERATOR_REMOVED, PAUSED, UNPAUSED |

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?"
}

| Field | Type | Required | Description | |-------|------|----------|-------------| | agentId | string | yes | UUID v4 identifying the agent (auto-generated by the SDK) | | message | string | yes | The question to ask |

Response (200):

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

Transfer Statuses

| Status | Description | |--------|-------------| | ACTIVE | Tokens locked in escrow, awaiting claim or cancellation | | CLAIMED | Recipient claimed the tokens | | CANCELLED | Sender cancelled and reclaimed the tokens | | EXPIRED | Transfer expired past its claimableUntil window |

Error Codes

Escrow Program Errors (Handshake)

| Code | Name | Description | |------|------|-------------| | 6000 | TransferAlreadyClaimed | Transfer has already been claimed | | 6001 | TransferAlreadyCancelled | Transfer has already been cancelled | | 6002 | TransferExpired | Transfer has expired | | 6003 | ClaimTooEarly | Cannot claim before claimableAfter timestamp | | 6004 | Unauthorized | Signer is not authorized for this action | | 6005 | PoolPaused | The token's escrow pool is temporarily paused — try again later | | 6006 | InsufficientFunds | Sender has insufficient token balance |

Account Program Errors (Silkysig)

| Code | Name | Description | |------|------|-------------| | 6000 | Unauthorized | Signer is not the owner or an operator on this account | | 6001 | ExceedsPerTxLimit | Transfer amount exceeds operator's per-transaction spending limit | | 6002 | ExceedsDailyLimit | Transfer exceeds operator daily limit (not yet enforced) | | 6003 | AccountPaused | Account is paused — operator transfers blocked until owner unpauses | | 6004 | MaxOperatorsReached | Account already has 3 operators (maximum) | | 6005 | OperatorNotFound | Specified operator not found on account | | 6006 | OperatorAlreadyExists | Operator is already on this account | | 6007 | InsufficientBalance | Account doesn't have enough tokens for this transfer | | 6008 | MathOverflow | Arithmetic overflow in calculation |

API Errors

| Error | HTTP | Description | |-------|------|-------------| | INVALID_PUBKEY | 400 | Invalid Solana public key format | | INVALID_AMOUNT | 400 | Amount must be positive | | MISSING_FIELD | 400 | Required field not provided | | TRANSFER_NOT_FOUND | 404 | No transfer found for the given PDA | | POOL_NOT_FOUND | 404 | No escrow pool found for this token | | TOKEN_NOT_FOUND | 400 | Token symbol or mint not recognized | | TX_FAILED | 400 | Transaction simulation or submission failed | | RATE_LIMITED | 429 | Too many faucet requests | | FAUCET_FAILED | 400 | Faucet airdrop failed |

Response Format

Success:

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

Error:

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

Security