Agent Quickstart

# 1. Install the Joyride CLI (ships the MCP server too)
npm install -g joyride-cli

# 2. Create a wallet
joyride setup

# 3. Authenticate (stores a JWT at ~/.joyride/session.json)
joyride login

# 4. Configure your MCP client — pick one:
joyride mcp install --client claude    # Claude Code
joyride mcp install --client cursor    # Cursor
joyride mcp install --client codex     # Codex

# 5. Restart your MCP client and start trading

npm install -g joyride-cli

joyride --help

joyride setup

joyride login

joyride mcp install --client claude     # Claude Code
joyride mcp install --client cursor     # Cursor
joyride mcp install --client codex      # Codex

{
  "mcpServers": {
    "joyride": {
      "command": "joyride",
      "args": ["mcp", "serve"],
      "env": {
        "JOYRIDE_HTTP_URL": "https://joyride.exchange"
      }
    }
  }
}

joyride · ✔ connected

// Save as .mjs or wrap in an async function
import fs from "node:fs";
import os from "node:os";
import path from "node:path";

// Read and validate the session
const session = JSON.parse(
  fs.readFileSync(path.join(os.homedir(), ".joyride/session.json"), "utf-8")
);
if (Date.now() >= session.expiresAt) {
  throw new Error("Session expired. Run `joyride login` to refresh.");
}

// Read: fetch balances from the query API (values are decimal strings, 8dp)
const resp = await fetch("https://joyride.exchange/api/query/balances", {
  headers: { Authorization: `Bearer ${session.token}` },
});
if (resp.status === 401) throw new Error("Token expired. Run `joyride login`.");
const balances = await resp.json();
console.log("Balance:", balances.available, "USDC");

// Public: list instruments (no auth needed)
const instruments = await fetch("https://joyride.exchange/api/v1/market/instruments").then(r => r.json());
console.log("Active instruments:", instruments.length);

# pip install requests
import json, os, time, requests

session = json.load(open(os.path.expanduser("~/.joyride/session.json")))
if time.time() * 1000 >= session["expiresAt"]:
    raise RuntimeError("Session expired. Run `joyride login` to refresh.")
headers = {"Authorization": f"Bearer {session['token']}"}

# Fetch balances from the query API (values are decimal strings, 8dp)
balances = requests.get("https://joyride.exchange/api/query/balances", headers=headers).json()
print(f"Balance: ${balances['available']}")

# List instruments (no auth needed)
instruments = requests.get("https://joyride.exchange/api/v1/market/instruments").json()
print(f"Active instruments: {len(instruments)}")

# requires jq (brew install jq / apt install jq)
TOKEN=$(jq -r .token ~/.joyride/session.json)
curl -H "Authorization: Bearer $TOKEN" https://joyride.exchange/api/query/balances
curl https://joyride.exchange/api/v1/market/instruments

// 1. Connect to the core trading WS: wss://joyride.exchange/api/client
// 2. Resume session with your JWT:
{"jsonrpc":"2.0","id":1,"method":"public/session_resume","params":{"session_token":"<jwt>"}}
// 3. Place a limit buy. Prices and quantities are decimal strings (8dp);
//    client_order_id and nonce are required. The order outcome arrives as an
//    async order_ack / fill / reject notification.
{"jsonrpc":"2.0","id":2,"method":"private/buy","params":{"instrument_name":"SOL_USDC-27APR26-87-C","price":"0.50000000","quantity":"1.00000000","order_type":"limit","client_order_id":1,"nonce":1}}

# Stream order book updates for an instrument
joyride watch book SOL_USDC-27APR26-87-C

# Stream the public trade feed
joyride watch trades SOL_USDC-27APR26-87-C

# Stream your fill notifications (requires joyride login)
joyride watch fills

// On the market-data WS (wss://joyride.exchange/api/md): subscribe by symbol
{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "public/subscribe",
  "params": {
    "instruments": ["SOL_USDC-27APR26-87-C"]
  }
}

# Public channels — no auth required
joyride watch book SOL_USDC-3MAR26-75-C
joyride watch trades SOL_USDC-3MAR26-75-C

# Private channels — require an active session (joyride login)
joyride watch fills
joyride watch settlements

joyride watch trades SOL_USDC-3MAR26-75-C | while IFS= read -r line; do
  echo "$line" | jq '{ts: .timestamp, px: .price, sz: .size}'
done

// Outbound: subscribe by symbol
{ "jsonrpc": "2.0", "id": 1, "method": "public/subscribe", "params": { "instruments": ["SOL_USDC-3MAR26-75-C"] } }

// Inbound: book snapshot/delta and trade notifications keyed by symbol
{ "jsonrpc": "2.0", "method": "subscription", "params": { "channel": "trades.SOL_USDC-3MAR26-75-C", "data": { /* trade */ } } }

export JOYRIDE_KEYSTORE_PASSWORD="any-strong-passphrase"
joyride setup --non-interactive --new-wallet

{
  "ok": true,
  "configPath": "/home/agent/.joyride/config.toml",
  "wallet": {
    "address": "B9vwMeHguq...",
    "keystorePath": "/home/agent/.joyride/wallets/B9vwMeHguq....json",
    "privateKey": "ngn812Sjsq..."
  }
}

export JOYRIDE_PRIVATE_KEY="<base58-encoded-ed25519-secret-key>"
joyride login
joyride balance

solana-keygen new --no-bip39-passphrase --outfile /tmp/joyride-key.json
# Convert the byte array to the Base58 form JOYRIDE_PRIVATE_KEY expects:
npx --yes -p @scure/base node -e '
  const fs = require("fs");
  const { base58 } = require("@scure/base");
  const bytes = Uint8Array.from(JSON.parse(fs.readFileSync("/tmp/joyride-key.json", "utf8")));
  console.log(base58.encode(bytes));
'

npx --yes -p @scure/base node -e '
  const c = require("crypto");
  const { base58 } = require("@scure/base");
  const kp = c.generateKeyPairSync("ed25519");
  const sk = kp.privateKey.export({ format: "der", type: "pkcs8" }).slice(-32);
  const pk = kp.publicKey.export({ format: "der", type: "spki" }).slice(-32);
  console.log(base58.encode(new Uint8Array(Buffer.concat([sk, pk]))));
'