Skip to content

Quick Start

Make your first multichain trade against a running Aspens Market Stack. There are two paths: a web UI (terminal-ui) and the CLI.

Prerequisites

  • Wallets for every chain you want to trade on (MetaMask, Rabby, Phantom, etc.)
  • A small native-gas balance on each chain you'll deposit from (you pay gas only to move funds in and out; placing orders is free)
  • The URL of an AMS instance — public, your own, or local

Path A: web UI

  1. Open the trading UI for the AMS instance you're using.
  2. Connect each wallet (one per chain involved in the markets you'll trade).
  3. Deposit — pick a token + chain, sign the deposit transaction.
  4. Place an order:
    • Limit: choose side (buy/sell), enter quantity and price.
    • Market: choose side and quantity; executes against best price.
    • Sign the order in your wallet (a signature only — no on-chain tx, no gas).
  5. Settle — once matched, you'll receive the counterparty's tokens on the destination chain. The fill is visible in the trading UI's Order History tab.
  6. Withdraw — return your available balance to your wallet anytime.

You retain custody throughout: deposited funds sit in the trading contract, and each open order reserves its own collateral lot against that balance. Cancelling always returns the lot to your available balance. Withdrawals cover the available portion — collateral behind a resting order has to be freed by cancelling or filling first.

Path B: CLI

cargo install --locked --git https://github.com/aspensprotocol/sdk aspens-cli
 
cat > .env <<'EOF'
ASPENS_MARKET_STACK_URL=https://your-ams-instance:50051
TRADER_PRIVKEY=<64-char hex EVM key, no 0x prefix>
# Add only if you trade on Solana chains:
# TRADER_PRIVKEY_SOLANA=<base58 keypair>
# Your own RPC per network — the stack masks rpc_url in its config, so
# deposit/withdraw need this. Key: ASPENS_RPC_URL_<NETWORK>.
ASPENS_RPC_URL_BASE_SEPOLIA=https://your-base-sepolia-rpc
EOF

Inspect the stack:

aspens-cli status
aspens-cli config                  # chains, tokens, markets
aspens-cli trader-public-key       # your derived EVM trader address

Trade:

aspens-cli deposit  base-sepolia USDC 1000      # 1000 USDC (human-readable)
aspens-cli buy-limit USDC/USDT 100 0.99
aspens-cli stream-orderbook USDC/USDT --historical
aspens-cli withdraw base-sepolia USDC 100

For an interactive session, run aspens-repl instead.

Path C: Rust SDK

use aspens::{AspensClient, DirectExecutor, load_trader_wallet_for_network};
use aspens::commands::{config, trading::deposit};
 
let client   = AspensClient::builder().build()?;
let executor = DirectExecutor;
let cfg      = executor.execute(config::get_config(client.stack_url().to_string()))?;
let wallet   = load_trader_wallet_for_network(&cfg, "base-sepolia")?;
 
executor.execute(deposit::call_deposit_from_config_with_wallet(
    "base-sepolia".into(), "USDC".into(), 1000, &wallet, cfg,
))?;

See the Developer Guide for the full surface, or cargo run --example quickstart in the SDK repo for an end-to-end script.

Next