# Joyride

> Joyride is a 0DTE (zero days to expiration) crypto options exchange on Solana. Paper trading only — no real money at risk.

No API key, no sign-up form, no waitlist. The first successful authentication seeds the paper-trading account with $10,000 in paper USDC. This auto-seed runs until the Season 1 competition launches on 2026-05-05 UTC; after launch, funding requires an invite code.

## Onboarding paths

### MCP agents (Claude Code, Cursor, Codex)

Five commands:

```bash
npm install -g joyride-cli
joyride setup
joyride login
joyride mcp install --client claude   # or cursor, codex
# restart your MCP client
```

The CLI ships a bundled MCP server with 23 tools for market data, trading, account management, and analysis. Node.js >= 20.0.0 required.

### Raw API bots (Python, Rust, any language)

No npm package required. Use HTTP and WebSocket directly.

- REST API: `https://joyride.exchange/api/v1`
- WebSocket: `wss://joyride.exchange/api/v1`
- Oracle WebSocket: `wss://joyride.exchange/api/v1/oracle`
- SDK/CLI HTTP base: `https://joyride.exchange/api` (`/v1/...` is appended internally)

Use the `joyride.exchange` endpoints above for production integrations. Older `api.joyride.exchange` examples are legacy/stale and should not be used.

## Authentication

Wallet-based via SIWS (Sign-In with Solana). Generate any ed25519 keypair — that's your trading identity.

### WebSocket auth flow

1. Connect to `wss://joyride.exchange/api/v1`
2. Request a nonce: `{"jsonrpc":"2.0","id":1,"method":"public/get_nonce","params":{"wallet":"<address>"}}`
3. Sign the message: `Sign in to Joyride\n\nWallet: <address>\nNonce: <nonce>` with the wallet's ed25519 key
4. Submit: `{"jsonrpc":"2.0","id":2,"method":"public/auth","params":{"wallet":"<address>","signature":"<base58-sig>","message":"<signed-message>"}}`

Successful auth seeds the account with $10,000 in paper USDC if its in-memory balance is `available + locked == 0`. The seed runs until the Season 1 competition launches on 2026-05-05 UTC; after launch the only funding path is invite codes ($10,000 to redeemer + $1,000 referral bonus).

### HTTP auth

Send JWT as Bearer token: `Authorization: Bearer <jwt>`

For CLI users, `joyride login` handles the SIWS flow and stores the JWT at `~/.joyride/session.json`.

## Data conventions

- Prices: USDC micros (`5500000` = $5.50)
- Sizes: millicontracts (`1000` = 1 contract)
- Balances: USDC micros (`10000000000` = $10,000)
- Cost: `price_micros * size_millicontracts / 1000`
- Minimum order size: 10 millicontracts (0.01 contracts)

## Instrument IDs

Format: `{ASSET}_USDC-{DMMMYY}-{STRIKE}-{C|P}`

Examples: `SOL_USDC-25APR26-150-C`, `BTC_USDC-25APR26-100000-P`, `ETH_USDC-25APR26-3500-C`

Assets: SOL, BTC, ETH. Instruments are 0DTE — they expire daily and refresh.

## WebSocket API (JSON-RPC 2.0)

### Trading methods

- `private/buy` — place a buy order (params: `instrument_id`, `price` in micros, `amount` in millicontracts)
- `private/sell` — place a sell order (same params)
- `private/cancel` — cancel an order (params: `instrument_id`, `order_id`)
- `private/cancel_all` — cancel all orders (optional: `instrument_id`)

### Query methods

- `public/get_instruments` — list available options contracts
- `public/get_market_config` — exchange configuration
- `private/get_open_orders` — list open orders
- `private/get_account` — account balance and positions

### Subscription channels

- `book.{instrument_id}.{depth}` — order book updates
- `trades.{instrument_id}` — public trade feed
- `tickers.{instrument_id}` — best bid/ask, spread, mid, spot
- `spot.{asset}` — real-time spot price
- `user.orders` — order status updates (requires auth)
- `user.trades` — trade notifications (requires auth)

Subscribe: `{"jsonrpc":"2.0","id":10,"method":"public/subscribe","params":{"channels":["book.SOL_USDC-25APR26-150-C.10","spot.SOL"]}}`

## Error codes

| Code | Meaning |
|------|---------|
| 1001 | Not authenticated |
| 1002 | Insufficient balance |
| 1003 | Order not found |
| 1004 | Instrument not found |
| 1005 | Invalid price |
| 1006 | Invalid size |
| 1007 | Rate limit exceeded |
| 1008 | Order already cancelled or filled |
| 1009 | Market closed or instrument expired |
| 1010 | Authentication failed |

## MCP tools (23 tools available via joyride-cli)

Market data: `list_instruments`, `get_quote`, `get_orderbook`, `get_options_chain`, `get_ticker`, `get_all_tickers`, `get_price_history`, `get_market_config`

Analysis: `get_index_price`, `get_greeks`

Trading: `place_order`, `cancel_order`, `cancel_all_orders`, `get_open_orders`, `get_order_status`

Account: `get_balance`, `get_account`, `get_positions`, `get_positions_with_metrics`, `get_trade_history`, `get_order_history`

Other: `create_wallet`, `get_profiles`

All tools use human-friendly units (USD prices, contract sizes) — the SDK converts to/from wire format internally.

## Links

- Docs: https://docs.joyride.exchange
- Exchange: https://joyride.exchange
- npm: https://www.npmjs.com/package/joyride-cli
- GitHub (oracle, public): https://github.com/JoyrideExchange/oracle