Skip to main content

​
Who this is for

Use this guide if you want to connect an AI agent to Joyride quickly without building against the raw HTTP or WebSocket APIs yourself. This is the recommended alpha path:
  1. install the Joyride alpha package you received from the team
  2. create or import a wallet with joyride setup
  3. export your keystore passphrase
  4. add Joyride MCP to your agent client
  5. verify the connection
  6. place a first paper trade

​
Before you start

  • Joyride CLI and MCP binaries installed from the alpha package you received from Joyride
  • joyride --help works in your terminal
  • command -v joyride-mcp returns a path in your terminal
  • Node.js >= 20.0.0
  • A local MCP client such as Claude Code or Cursor
Current mode: Paper trading only. No real money is at risk. Important: The first successful Joyride authentication creates a paper-trading account with a starting balance of $10,000.00.

​
1. Create or import a wallet

Run the setup wizard: 
joyride setup
Choose one of:
  • Create new wallet if you want a fresh paper-trading identity
  • Import existing wallet if Joyride already told you to use a specific wallet
The wizard writes:
  • config to ~/.joyride/config.toml
  • encrypted keystores to ~/.joyride/wallets/
Back up the private key shown during wallet creation. The keystore is encrypted locally, but the private key display is your recovery path.

​
2. Export your keystore passphrase

The MCP server runs non-interactively, so it needs the same passphrase you used during setup: 
export JOYRIDE_KEYSTORE_PASSWORD="your-passphrase"
If you prefer advanced automation, you can use JOYRIDE_PRIVATE_KEY instead, but the keystore flow is the recommended alpha path.

​
3. Add Joyride MCP to your agent

​
Claude Code

Create .mcp.json in your project root: 
{
  "mcpServers": {
    "joyride": {
      "command": "joyride-mcp",
      "args": [],
      "env": {
        "JOYRIDE_WS_URL": "wss://joyride.exchange/api/v1",
        "JOYRIDE_HTTP_URL": "https://joyride.exchange/api",
        "JOYRIDE_KEYSTORE_PASSWORD": "<your-keystore-passphrase>"
      }
    }
  }
}

​
Cursor

Create .cursor/mcp.json: 
{
  "mcpServers": {
    "joyride": {
      "command": "joyride-mcp",
      "args": [],
      "env": {
        "JOYRIDE_WS_URL": "wss://joyride.exchange/api/v1",
        "JOYRIDE_HTTP_URL": "https://joyride.exchange/api",
        "JOYRIDE_KEYSTORE_PASSWORD": "<your-keystore-passphrase>"
      }
    }
  }
}

​
Codex and other MCP-capable clients

If your client can launch a local stdio MCP server, reuse the same Joyride command and environment variables shown above:
  • command: joyride-mcp
  • env: JOYRIDE_WS_URL, JOYRIDE_HTTP_URL, JOYRIDE_KEYSTORE_PASSWORD
If your client only supports remote HTTP MCP, do not treat that as the default alpha path yet. Joyride’s hosted MCP endpoint is still preview-only for external users. If you store these files in a repo, add them to .gitignore. They contain secrets.

​
4. Restart and verify

Restart your MCP client, then verify the Joyride server is connected. In Claude Code: 
/mcp
You should see: 
joyride · ✔ connected

​
5. Try a first session

Start with read-only prompts:
  • List available SOL instruments
  • Get a quote for SOL_USDC-3MAR26-75-C
  • Show my balance
Then try a paper-trading prompt:
  • Place a limit buy for 1 contract of SOL_USDC-3MAR26-75-C at $4.00
Do not hard-code the example instrument IDs above. Joyride lists same-day contracts that refresh daily, so available instruments can change between sessions.

​
Supported clients

ClientStatus
Claude CodeSupported and tested
CursorSupported and tested
VS Code CopilotConfiguration documented; validate before broad alpha rollout
OpenClawNeeds the local wallet-based config from the repo collateral updates
CodexExperimental; use the generic stdio MCP pattern and validate before calling it supported

​
Troubleshooting

​
Joyride: No config found

Run: 
joyride setup

​
Error: JOYRIDE_KEYSTORE_PASSWORD env var is required

Your MCP client is launching joyride-mcp without the passphrase needed to decrypt your keystore. Add JOYRIDE_KEYSTORE_PASSWORD to the MCP config and restart the client.

​
Wallet not configured

Run: 
joyride wallet show
If no wallet is configured, re-run joyride setup or create one explicitly with joyride wallet create.

​
The instrument examples do not exist

Same-day instruments refresh continuously as the market rolls. Always start by asking the agent to list available instruments or options chains instead of assuming an older example contract is still live. If you need the exact schedule, see Trading Hours and Rollover.