prism (CLI)

Command-line tool for the Prism wallet infrastructure. Create wallets, execute swaps, check cross-chain status, and inspect balances — all from the terminal.

Works with the same wallet and aggregator stack as the SDK packages.

Install

npm install -g @prism-ing/cli

Or run without installing:

npx @prism-ing/cli swap --from USDC:base --to WETH:base --amount 1000000 --dry-run

Quick Start

# 1. Create a wallet (persists at ~/.ows/)
prism wallet create --name my-agent

# 2. Configure your aggregator
prism config set aggregator-url https://your-aggregator.fly.dev/v1

# 3. Check connectivity
prism doctor

# 4. Get a quote (no execution)
prism swap --from USDC:base --to WETH:base --amount 1000000 --dry-run

# 5. Execute the swap
prism swap --from USDC:base --to WETH:base --amount 1000000

Commands

prism wallet

Manage OWS wallets stored at ~/.ows/.

prism wallet create --name <name>   # Create or load a named wallet
prism wallet show   --name <name>   # Show addresses for a wallet
prism wallet list                   # List all wallet names

Example:

$ prism wallet create --name trading-agent
✓  Wallet ready
   EVM:     0x71C7656EC7ab88b098defB751B7401B5f6d8976F
   Solana:  DRpbCBMxVnDK7maPM5tGv6MvB3v1sRMC86PZ8okm21hy

Same name = same keys = same addresses on every run. Keys persist encrypted at ~/.ows/.

JSON output:

prism wallet create --name my-agent --json
# {"evmAddress":"0x...","solanaAddress":"...","walletName":"my-agent"}

prism swap

Quote and execute swaps. Supports same-chain EVM, same-chain Solana, and cross-chain.

prism swap --from <asset> --to <asset> --amount <amount> [options]

Arguments:

| Flag | Description | Default | |------|-------------|---------| | --from | Source asset. Format: SYMBOL:chain or 0xAddress:chainId | required | | --to | Destination asset. Same format as --from | required | | --amount | Amount in smallest unit (e.g. 1000000 for 1 USDC) | required | | --slippage | Slippage tolerance in basis points | 50 | | --provider | Pin to a specific solver (see table below) | best price | | --smart-account | OneBalance Kernel v3.1 smart account address | — | | --dry-run | Fetch quote only, do not execute | false | | --no-wait | Submit cross-chain swap without polling for completion | false | | --json | Output as JSON | false |

Solvers (use with --provider):

| Value | Route | Notes | |-------|-------|-------| | kyberswap | Same-chain EVM | Default for most EVM routes | | jupiter | Same-chain Solana | Best for Solana routes | | okx-dex | Same-chain EVM or Solana | Alternative to kyberswap/jupiter | | swaps-xyz | Same-chain or cross-chain bridge | Bridge fallback | | onebalance | Cross-chain fast-path | Requires --smart-account | | fynd | Same-chain EVM | Optional, server-side dep | | bf-evm | Same-chain EVM | Optional, server-side dep | | bf-solana | Same-chain Solana | Optional, server-side dep |

Examples:

# Same-chain EVM: USDC → WETH on Base
prism swap --from USDC:base --to WETH:base --amount 1000000

# Same-chain Solana: USDC → SOL
prism swap --from USDC:solana --to SOL:solana --amount 1000000

# Cross-chain: USDC on Base → USDC on Arbitrum (bridge)
prism swap --from USDC:base --to USDC:arbitrum --amount 5000000

# Cross-chain: OneBalance fast-path (requires smart account)
prism swap --from USDC:base --to USDC:arbitrum --amount 5000000 \
  --provider onebalance \
  --smart-account 0xYourKernelSmartAccountAddress

# Quote only — no execution
prism swap --from USDC:base --to WETH:base --amount 1000000 --dry-run

# Use a specific solver
prism swap --from USDC:base --to WETH:base --amount 1000000 --provider kyberswap

# Submit cross-chain without waiting for completion
prism swap --from USDC:base --to USDC:arbitrum --amount 5000000 --no-wait

# JSON output (pipe to jq)
prism swap --from USDC:base --to WETH:base --amount 1000000 --dry-run --json | jq '.provider'

JSON output shape:

For dry-run and confirmed same-chain swaps, the JSON is the raw quote object:

{
  "quoteId": "qr_abc123",
  "provider": "kyberswap",
  "routeType": "same-chain-evm",
  "fromAsset": { "symbol": "USDC", "chain": "base" },
  "toAsset": { "symbol": "WETH", "chain": "base" },
  "amountIn": "1000000",
  "amountOut": "413821",
  "netAmountOut": "412000",
  "priceImpactBps": 4
}

For cross-chain swaps that complete while polling:

{
  "quote": { ... },
  "execution": { "status": "pending", "quoteId": "qr_abc123" },
  "finalStatus": { "quoteId": "qr_abc123", "status": "COMPLETED", "txHash": "0x..." }
}

prism status

Check the status of a cross-chain swap.

prism status <quoteId>
prism status <quoteId> --json

Example:

$ prism status qr_8f3a2b1c9d4e
  Quote ID:      qr_8f3a2b1c9d4e
  Status:        COMPLETED
  Tx hash:       0x4d2a9f8b3c1e...

prism balance

Show the aggregated balance across all chains for the current wallet.

prism balance
prism balance --wallet <name>
prism balance --json

Requires the wallet to be configured with OneBalance (see createOneBalanceProvider in @prism-ing/wallet).

prism tokens

List all tokens available on the connected aggregator.

prism tokens
prism tokens --json

prism chains

List all chains available on the connected aggregator.

prism chains
prism chains --json

prism config

Read and write the CLI configuration file (~/.prism/config.json).

prism config set <key> <value>
prism config show

Config keys:

| Key | Description | Default | |-----|-------------|---------| | aggregator-url | Aggregator base URL (must include /v1) | — | | wallet-name | Default wallet name used by all commands | default |

Config file location: ~/.prism/config.json

{
  "aggregatorUrl": "https://your-aggregator.fly.dev/v1",
  "walletName": "trading-agent"
}

RPC Configuration

The CLI ships with no bundled RPC keys. You must supply your own endpoints from a provider such as Alchemy or Helius.

Recommended: ~/.prism/.env

Create ~/.prism/.env (never committed, never published):

# ~/.prism/.env
PRISM_RPC_1=https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY
PRISM_RPC_8453=https://base-mainnet.g.alchemy.com/v2/YOUR_KEY
PRISM_RPC_42161=https://arb-mainnet.g.alchemy.com/v2/YOUR_KEY
PRISM_RPC_137=https://polygon-mainnet.g.alchemy.com/v2/YOUR_KEY
PRISM_RPC_10=https://opt-mainnet.g.alchemy.com/v2/YOUR_KEY
PRISM_SOL_RPC=https://mainnet.helius-rpc.com/?api-key=YOUR_KEY

Alternative: environment variables

The same variables can be set in your shell or CI environment — they take priority over the .env file:

export PRISM_RPC_8453=https://base-mainnet.g.alchemy.com/v2/YOUR_KEY
export PRISM_SOL_RPC=https://mainnet.helius-rpc.com/?api-key=YOUR_KEY
prism swap --from USDC:base --to WETH:base --amount 1000000

Variable reference:

| Variable | Chain | |----------|-------| | PRISM_RPC_1 | Ethereum mainnet | | PRISM_RPC_8453 | Base | | PRISM_RPC_42161 | Arbitrum One | | PRISM_RPC_137 | Polygon | | PRISM_RPC_10 | Optimism | | PRISM_RPC_130 | Unichain | | PRISM_SOL_RPC | Solana mainnet |

Without RPC endpoints configured, swap execution will fail. --dry-run (quote only) works without RPCs because no on-chain calls are made.

prism doctor

Check aggregator connectivity and wallet configuration.

prism doctor
prism doctor --json

Reports: aggregator reachability, wallet exists, config file location, any missing env vars.

Asset Formats

| Format | Example | Notes | |--------|---------|-------| | Symbol + chain | USDC:base | Resolved by the aggregator | | Symbol + chain | SOL:solana | Native SOL on Solana | | Address + chainId | 0xA0b8...:8453 | Specific token by contract address | | OneBalance aggregated | ob:usdc | Cross-chain, any chain (OneBalance routes) |

Supported chain shorthands: base, arbitrum, ethereum, optimism, polygon, solana, avalanche, bnb, linea, blast.

JSON Output and Scripting

Every command supports --json for machine-readable output. Useful for scripting.

# Extract the winning provider
PROVIDER=$(prism swap --from USDC:base --to WETH:base --amount 1000000 --dry-run --json | jq -r '.provider')
echo "Best provider: $PROVIDER"

# Get wallet EVM address
EVM=$(prism wallet create --name my-agent --json | jq -r '.evmAddress')
echo "EVM address: $EVM"

# Check swap status and extract tx hash
TX=$(prism status qr_abc123 --json | jq -r '.txHash')

Agent Integration

The CLI is designed for use in agent workflows and CI scripts.

Test all solvers:

# Dry-run every solver to confirm they're live after a deployment
for PROVIDER in kyberswap jupiter okx-dex swaps-xyz; do
  echo "Testing $PROVIDER..."
  prism swap --from USDC:base --to WETH:base --amount 1000000 \
    --provider $PROVIDER --dry-run --json | jq -r '"\(.provider): \(.netAmountOut)"'
done

Automated cross-chain transfer:

#!/usr/bin/env bash
set -euo pipefail

RESULT=$(prism swap \
  --from USDC:base \
  --to   USDC:arbitrum \
  --amount 10000000 \
  --json)

STATUS=$(echo "$RESULT" | jq -r '.finalStatus.status // .execution.status')
QUOTE_ID=$(echo "$RESULT" | jq -r '.quote.quoteId')

echo "Swap $QUOTE_ID: $STATUS"

Wallet Security Model

The CLI stores wallets via the OWS (Open Wallet Standard) encrypted vault:

• Keys are persisted at ~/.ows/<wallet-name>.json
• Encrypted with AES-256-GCM, key derived via scrypt
• No seed phrase or private key is ever printed or logged
• Same wallet name resolves to the same keys on every run
• --json output only includes addresses, never key material

To use a passphrase for additional protection, set OWS_PASSPHRASE in your environment before running any prism command.

Documentation

• @prism-ing/wallet — Wallet SDK, session keys, social recovery
• @prism-ing/onebalance — Cross-chain balance and account abstraction
• @prism-ing/swap-router — Multi-solver DEX aggregation

License

MIT