API Overview

Cupdiction exposes a public REST API for reading market data. All endpoints return JSON.

⚠️

The Cupdiction API is in alpha. Endpoints and response shapes may change without notice. Breaking changes will be communicated in release notes.

Base URL

https://cupdiction.com/api

All requests are HTTPS. No authentication is required for read endpoints.

Write endpoints (placing orders, withdrawing) require a Privy bearer token.

Authorization: Bearer <privy_access_token>

Obtain a token via Privy’s getAccessToken() method in the Cupdiction frontend SDK.

All endpoints return JSON. Successful responses have HTTP status 2xx.

Errors return a JSON object with an error field:

{
  "error": "Market not found"
}

Read endpoints: 100 requests/minute per IP. Write endpoints: 12 requests/minute per authenticated user.

Method	Path	Description
`GET`	`/api/markets`	List markets
`GET`	`/api/markets/{id}`	Get market by ID
`GET`	`/api/markets/{id}/history`	Price history (OHLCV candles)
`GET`	`/api/bags/tokens`	List Bags.fm tokens
`GET`	`/api/bags/tokens/{mint}`	Token detail + markets
`GET`	`/api/bags/receipts`	Recent resolved Bags markets
`GET`	`/api/bags/fee-races`	Active fee race markets
`GET`	`/api/wallet/balances`	Your balances (auth required)
`GET`	`/api/wallet/positions`	Your positions (auth required)
`POST`	`/api/orders`	Place a trade (auth required)
`POST`	`/api/orders/quote`	Get a trade quote (no auth)
`GET`	`/api/queue`	Your trade queue (auth required)
`POST`	`/api/queue`	Add to queue (auth required)
`DELETE`	`/api/queue/{id}`	Cancel queue entry (auth required)