### Get Balance & Allowance Response Example

Source: https://github.com/dilettante-trading/polyoxide/blob/main/docs/specs/clob/account.md

Example JSON response structure for the GET /balance-allowance endpoint, showing user's balance and allowances.

```json
{
  "balance": "string",
  "allowances": {"address": "amount"}
}
```

--------------------------------

### Quick start: List open markets

Source: https://github.com/dilettante-trading/polyoxide/blob/main/polyoxide-gamma/README.md

A basic example demonstrating how to initialize the Gamma client and list the top 10 open markets sorted by volume.

```rust
use polyoxide_gamma::Gamma;

#[tokio::main]
async fn main() -> Result<(), polyoxide_gamma::GammaError> {
    let gamma = Gamma::builder().build()?;

    // List open markets, sorted by volume
    let markets = gamma.markets() 
        .list() 
        .open(true) 
        .order("volume") 
        .ascending(false) 
        .limit(10) 
        .send() 
        .await?;

    for m in &markets {
        println!("{}: vol={}, liq={}", m.question, m.volume, m.liquidity);
    }

    Ok(())
}

```

--------------------------------

### Get Market Positions Example

Source: https://github.com/dilettante-trading/polyoxide/blob/main/docs/specs/data/positions.md

This example demonstrates how to retrieve market positions for a specific user and filter the results. It uses curl to make the request and jq to parse the JSON response.

```bash
# Get positions for a known user
curl -s 'https://data-api.polymarket.com/positions?user=0xFeA4cB3dD4ca7CefD3368653B7D6FF9BcDFca604&limit=1' | jq '.[0] | {asset, title, size, curPrice}'
```

--------------------------------

### Install Polyoxide CLI using install script

Source: https://github.com/dilettante-trading/polyoxide/blob/main/polyoxide-cli/README.md

Downloads and installs polyoxide-cli binaries directly from Github releases using a provided script.

```bash
curl -fsSL https://raw.githubusercontent.com/dilettante-trading/polyoxide/main/scripts/install.sh | sh
```

--------------------------------

### Commit Changes Example

Source: https://github.com/dilettante-trading/polyoxide/blob/main/docs/plans/2026-03-18-api-specs-implementation.md

Example Git commands to stage and commit documentation changes.

```bash
git add docs/specs/clob/orders.md
git commit -m "docs: add CLOB orders and trading spec"
```

--------------------------------

### Install Polyoxide CLI

Source: https://github.com/dilettante-trading/polyoxide/blob/main/README.md

Install the polyoxide-cli tool using cargo or by downloading binaries.

```bash
cargo install polyoxide-cli
```

```bash
curl -fsSL https://raw.githubusercontent.com/dilettante-trading/polyoxide/main/scripts/install.sh | sh
```

--------------------------------

### Install Polyoxide with Specific Features

Source: https://github.com/dilettante-trading/polyoxide/blob/main/README.md

Install polyoxide with specific features like only Gamma (market data), CLOB (trading), Data API, or WebSocket.

```bash
# Market data only
cargo add polyoxide --no-default-features --features gamma

# Trading only
cargo add polyoxide --no-default-features --features clob

# Data API only
cargo add polyoxide --no-default-features --features data

# WebSocket only
cargo add polyoxide --no-default-features --features ws
```

--------------------------------

### Get Profile by User Address Response Example

Source: https://github.com/dilettante-trading/polyoxide/blob/main/docs/specs/gamma/user.md

Example JSON response for a user's detailed profile. This schema includes additional fields like UTM tracking parameters, wallet activation status, and certification request details.

```json
{
  "id": "p1",
  "name": "polytrader",
  "user": 123,
  "referral": "abc",
  "createdBy": 1,
  "updatedBy": 1,
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-06-15T12:00:00Z",
  "utmSource": "twitter",
  "utmMedium": "social",
  "utmCampaign": "summer",
  "utmContent": "banner",
  "utmTerm": "polymarket",
  "walletActivated": true,
  "pseudonym": "poly_anon",
  "displayUsernamePublic": true,
  "profileImage": "https://example.com/avatar.png",
  "bio": "DeFi enthusiast",
  "proxyWallet": "0xproxy...",
  "profileImageOptimized": null,
  "isCloseOnly": false,
  "isCertReq": false,
  "certReqDate": null
}
```

--------------------------------

### Example: Get Leaderboard Data

Source: https://github.com/dilettante-trading/polyoxide/blob/main/CLAUDE.md

Shows how to retrieve data from the Data API's leaderboard endpoint. The request is built and sent asynchronously.

```rust
data.leaderboard().get().send().await?
```

--------------------------------

### Get Simplified Markets

Source: https://github.com/dilettante-trading/polyoxide/blob/main/docs/specs/clob/orders.md

Fetches simplified market data. Use this to get a list of markets without authentication. The example shows how to retrieve the first market from the paginated response.

```bash
# Get simplified markets (public, no auth needed)
curl -s 'https://clob.polymarket.com/simplified-markets?next_cursor=MA==' | jq '.data[0]'
```

--------------------------------

### Build Polyoxide from Source

Source: https://github.com/dilettante-trading/polyoxide/blob/main/polyoxide-py/README.md

Install and build the Polyoxide library from its source code using pip and maturin. Ensure you have Rust and Python 3.8+ installed.

```bash
pip install maturin
maturin develop --release
```

--------------------------------

### Get Active Reward Configurations Response Example

Source: https://github.com/dilettante-trading/polyoxide/blob/main/docs/specs/clob/rewards.md

This JSON structure details the current active reward configurations for markets. It includes pagination information and a list of reward configurations per market.

```json
{
  "limit": 500,
  "count": 1,
  "next_cursor": "string",
  "data": [
    {
      "condition_id": "string",
      "rewards_max_spread": 0.0,
      "rewards_min_size": 0.0,
      "rewards_config": [],
      "native_daily_rate": 0.0,
      "total_daily_rate": 0.0
    }
  ]
}
```

--------------------------------

### Get User Public Profile Response Example

Source: https://github.com/dilettante-trading/polyoxide/blob/main/docs/specs/gamma/user.md

Example JSON response for a user's public profile. This schema includes basic user information like username, bio, and profile image.

```json
{
  "proxyWallet": "0xproxy...",
  "address": "0xsigner...",
  "id": "u1",
  "name": "polytrader",
  "createdAt": "2024-01-15T10:00:00Z",
  "profileImage": "https://example.com/avatar.png",
  "displayUsernamePublic": true,
  "bio": "DeFi enthusiast",
  "pseudonym": "poly_anon",
  "xUsername": "polytrader_x",
  "verifiedBadge": true,
  "users": [
    {"id": "uid-1", "creator": true, "mod": false},
    {"id": "uid-2", "creator": false, "mod": true}
  ]
}
```

--------------------------------

### Install Polyoxide

Source: https://github.com/dilettante-trading/polyoxide/blob/main/polyoxide-py/README.md

Install the polyoxide package using pip. Wheels are available for major operating systems and architectures.

```bash
pip install polyoxide
```

--------------------------------

### Get Sports Metadata Example

Source: https://github.com/dilettante-trading/polyoxide/blob/main/docs/specs/gamma/sports.md

Retrieves all sports metadata, including configuration and assets. No authentication or query parameters are required.

```json
[
  {
    "id": 1,
    "sport": "Basketball",
    "image": "https://example.com/nba.png",
    "resolution": "...",
    "ordering": "...",
    "tags": "...",
    "series": "...",
    "createdAt": "2024-01-01T00:00:00Z"
  }
]
```

--------------------------------

### Install Polyoxide CLI using Cargo

Source: https://github.com/dilettante-trading/polyoxide/blob/main/polyoxide-cli/README.md

Installs the polyoxide-cli tool from crates.io using the Cargo package manager.

```bash
cargo install polyoxide-cli
```

--------------------------------

### Add polyoxide-clob to Project

Source: https://github.com/dilettante-trading/polyoxide/blob/main/polyoxide-clob/README.md

Install the polyoxide-clob crate using Cargo. This is the basic installation command.

```rust
cargo add polyoxide-clob
```

--------------------------------

### Get Batch Price History Response

Source: https://github.com/dilettante-trading/polyoxide/blob/main/docs/specs/clob/markets.md

Example response structure for batch price history, showing historical price data for an asset.

```json
{
  "history": {
    "asset_id_1": [{"t": 1700000000, "p": 0.5}]
  }
}
```

--------------------------------

### Get User Earnings by Date Response Example

Source: https://github.com/dilettante-trading/polyoxide/blob/main/docs/specs/clob/rewards.md

This JSON structure represents the response when fetching a user's earnings for a specific date. It includes pagination details and a list of earnings data for different conditions and assets.

```json
{
  "limit": 100,
  "count": 1,
  "next_cursor": "string",
  "data": [
    {
      "date": "string — ISO-8601",
      "condition_id": "string",
      "asset_address": "string",
      "maker_address": "string",
      "earnings": 0.0,
      "asset_rate": 0.0
    }
  ]
}
```

--------------------------------

### Send Heartbeat Response Example

Source: https://github.com/dilettante-trading/polyoxide/blob/main/docs/specs/clob/account.md

Example JSON response for the POST /heartbeats endpoint, indicating a successful heartbeat.

```json
{"status": "ok"}
```

--------------------------------

### Send Heartbeat (v1) Request Example

Source: https://github.com/dilettante-trading/polyoxide/blob/main/docs/specs/clob/account.md

Example JSON request for the POST /v1/heartbeats endpoint, used for initiating or continuing a session with a heartbeat ID.

```json
{"heartbeat_id": ""}
```

--------------------------------

### Add Polyoxide Crate (Trading Only)

Source: https://github.com/dilettante-trading/polyoxide/blob/main/polyoxide/README.md

Install the Polyoxide crate with only the 'clob' feature for trading.

```bash
cargo add polyoxide --no-default-features --features clob
```

--------------------------------

### Get builder leaderboard

Source: https://github.com/dilettante-trading/polyoxide/blob/main/polyoxide-cli/README.md

Retrieves the builder leaderboard with default time period.

```bash
polyoxide data builders leaderboard
```

--------------------------------

### Get Ban Status Response Example

Source: https://github.com/dilettante-trading/polyoxide/blob/main/docs/specs/clob/account.md

Example JSON response for the GET /auth/ban-status/closed-only endpoint, indicating the ban status.

```json
{"closed_only": false}
```

--------------------------------

### Create, Sign, and Post Order (Step-by-Step)

Source: https://github.com/dilettante-trading/polyoxide/blob/main/polyoxide-clob/README.md

Demonstrates the individual steps for placing an order: creating the order parameters, signing the order, and then posting the signed order. Requires authenticated access.

```rust
// Or step-by-step: create, sign, then post
let order = clob.create_order(&params, None).await?;
let signed = clob.sign_order(&order).await?;
let response = clob.post_order(&signed, OrderKind::Gtc, false).await?;
```

--------------------------------

### Example: List Open Markets

Source: https://github.com/dilettante-trading/polyoxide/blob/main/CLAUDE.md

Demonstrates using the Gamma API to list open markets. Query parameters are chained using builder methods before sending the request.

```rust
gamma.markets().list().open(true).send().await?
```

--------------------------------

### Get Neg Risk Response

Source: https://github.com/dilettante-trading/polyoxide/blob/main/docs/plans/2026-03-18-api-specs-implementation.md

Example JSON response for the GET /neg-risk endpoint.

```json
{"neg_risk": true}
```

--------------------------------

### Get Notifications Response Example

Source: https://github.com/dilettante-trading/polyoxide/blob/main/docs/specs/clob/notifications.md

Example structure of a successful response when fetching notifications. The 'payload' field can contain various data types depending on the notification type.

```json
[
{
  "id": "string",
  "owner": "string",
  "type": 0,
  "payload": {},
  "timestamp": "string"
}]

```

--------------------------------

### Initialize CLOB Client with Private Key and Credentials

Source: https://github.com/dilettante-trading/polyoxide/blob/main/polyoxide-clob/README.md

Create a CLOB client by directly providing a private key and credentials. This is a shorthand for authenticated client creation.

```rust
use polyoxide_clob::{Account, Chain, Clob, ClobBuilder, Credentials};

// Shorthand: private key + credentials directly
let clob = Clob::new("0xprivate_key", credentials)?;
```

--------------------------------

### REST API Usage Example

Source: https://github.com/dilettante-trading/polyoxide/blob/main/README.md

Demonstrates how to use the Polyoxide SDK to interact with Polymarket's REST APIs, including fetching markets, user positions, and checking balances. Ensure your account credentials are set in environment variables or use the `keychain` feature.

```rust
use polyoxide::prelude::*;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Load account from environment variables
    // (or use Account::from_keychain() with the `keychain` feature)
    let account = Account::from_env()?;

    let client = Polymarket::builder(account)
        .chain(Chain::PolygonMainnet)
        .build()?;

    // List open markets via Gamma API
    let markets = client.gamma.markets()
        .list()
        .open(true)
        .limit(10)
        .send()
        .await?;

    // Get user positions via Data API
    let positions = client.data
        .user("0x1234...")
        .list_positions()
        .send()
        .await?;

    // Check balance via CLOB API (requires auth)
    let balance = client.clob
        .account_api()? 
        .balance_allowance("token_id")
        .send()
        .await?;

    Ok(())
}
```

--------------------------------

### Add Polyoxide Crate (Market Data Only)

Source: https://github.com/dilettante-trading/polyoxide/blob/main/polyoxide/README.md

Install the Polyoxide crate with only the 'gamma' feature for market data.

```bash
cargo add polyoxide --no-default-features --features gamma
```

--------------------------------

### Get Nonce using cURL

Source: https://github.com/dilettante-trading/polyoxide/blob/main/docs/specs/relay/transactions.md

Example using cURL to retrieve the nonce for a specific wallet address and type. The response is piped to `jq` for pretty-printing.

```bash
# Get nonce
curl -s 'https://relayer-v2.polymarket.com/nonce?address=0xFeA4cB3dD4ca7CefD3368653B7D6FF9BcDFca604&type=SAFE' | jq .

```

--------------------------------

### Initialize RelayClient with Builder API Credentials

Source: https://github.com/dilettante-trading/polyoxide/blob/main/polyoxide-relay/README.md

Configure and create a RelayClient using API key and secret for authentication. Ensure your private key is valid.

```rust
use polyoxide_relay::{RelayClient, BuilderAccount, BuilderConfig};

let config = BuilderConfig::new(
    "your-api-key".into(),
    "your-secret".into(),
    Some("your-passphrase".into()),
);
let account = BuilderAccount::new("0xprivatekey...", Some(config))?;
let client = RelayClient::from_account(account)?;
```

--------------------------------

### Get Reward Percentages Response Example

Source: https://github.com/dilettante-trading/polyoxide/blob/main/docs/specs/clob/rewards.md

This JSON object shows the reward percentages for different condition IDs. It maps each condition ID to its corresponding percentage.

```json
{"0x296ea...": 20, "0xbd31d...": 20}
```

--------------------------------

### Load Account from Environment Variables

Source: https://github.com/dilettante-trading/polyoxide/blob/main/polyoxide-clob/README.md

Create an Account object by loading credentials (private key, API key, secret, passphrase) from environment variables. Ensure these variables are set before running.

```rust
use polyoxide_clob::{Account, Credentials};

// From environment variables
let account = Account::from_env()?;
```

--------------------------------

### Get Series Summary by ID Example Response

Source: https://github.com/dilettante-trading/polyoxide/blob/main/docs/specs/gamma/series.md

This JSON shows a sample response for retrieving a series summary by its ID. It includes key dates and week information relevant to the series.

```json
{
  "id": "s1",
  "title": "NFL 2025",
  "slug": "nfl-2025",
  "eventDates": ["2025-09-07", "2025-09-14"],
  "eventWeeks": [1, 2],
  "earliest_open_week": 1,
  "earliest_open_date": "2025-09-07"
}
```

--------------------------------

### Add Polyoxide Crate to Project

Source: https://github.com/dilettante-trading/polyoxide/blob/main/README.md

Install the main polyoxide crate for general use. This includes all features by default.

```bash
cargo add polyoxide
```

--------------------------------

### Get Total Earnings by Date Response Example

Source: https://github.com/dilettante-trading/polyoxide/blob/main/docs/specs/clob/rewards.md

This JSON array represents the aggregated total earnings for a user by date. Each object details earnings for a specific asset and maker address.

```json
[
  {
    "date": "string",
    "asset_address": "string",
    "maker_address": "string",
    "earnings": 0.0,
    "asset_rate": 0.0
  }
]
```

--------------------------------

### Async Market Data Fetching

Source: https://github.com/dilettante-trading/polyoxide/blob/main/polyoxide-py/README.md

Example of fetching the latest open markets asynchronously using the Gamma client. Requires an active asyncio event loop.

```python
import asyncio
from polyoxide import Gamma

async def main():
    gamma = Gamma()
    markets = await gamma.markets().list(limit=5, open=True)
    for m in markets:
        print(f"{m.question}  --  {m.slug}")

asyncio.run(main())
```

--------------------------------

### Get Current Rebated Fees Response Example

Source: https://github.com/dilettante-trading/polyoxide/blob/main/docs/specs/clob/rewards.md

This JSON array shows the rebated fees for a maker address on a specific date. Each object details the rebated fees for a particular condition and asset.

```json
[
  {
    "date": "2026-02-27",
    "condition_id": "string",
    "asset_address": "string",
    "maker_address": "string",
    "rebated_fees_usdc": "0.237519"
  }
]
```

--------------------------------

### List Tags with Limit

Source: https://github.com/dilettante-trading/polyoxide/blob/main/docs/specs/gamma/tags.md

Demonstrates how to list tags using the /tags endpoint with a limit parameter. This example uses curl and jq to fetch and display the first tag from the response.

```bash
curl -s 'https://gamma-api.polymarket.com/tags?limit=5' | jq '.[0]'
```

--------------------------------

### Load Account from OS Keychain

Source: https://github.com/dilettante-trading/polyoxide/blob/main/polyoxide-clob/README.md

Create an Account object by retrieving credentials from the operating system's keychain. This requires the 'keychain' feature to be enabled.

```rust
use polyoxide_clob::{Account, Credentials};

// From the OS keychain (feature `keychain`)
let account = Account::from_keychain()?;
```

--------------------------------

### Configure RelayClient from Environment Variables

Source: https://github.com/dilettante-trading/polyoxide/blob/main/polyoxide-relay/README.md

Initialize a RelayClient using default settings, pulling the relayer URL and chain ID from environment variables. Requires an account to be provided separately.

```rust
let client = RelayClient::default_builder()? 
    .with_account(account)
    .build()?;
```

--------------------------------

### Add Polyoxide Crate (Full Features)

Source: https://github.com/dilettante-trading/polyoxide/blob/main/polyoxide/README.md

Install the Polyoxide crate with all features, including WebSocket support.

```bash
cargo add polyoxide --no-default-features --features full
```

--------------------------------

### Build Polyoxide CLI from source

Source: https://github.com/dilettante-trading/polyoxide/blob/main/polyoxide-cli/README.md

Builds the polyoxide-cli tool from source code using Cargo in release mode.

```bash
cargo build -p polyoxide-cli --release
```

--------------------------------

### Load Account from JSON File

Source: https://github.com/dilettante-trading/polyoxide/blob/main/polyoxide-clob/README.md

Create an Account object by loading credentials from a specified JSON file. The file should contain the necessary API credentials.

```rust
use polyoxide_clob::{Account, Credentials};

// From a JSON file
let account = Account::from_file("config/account.json")?;
```

--------------------------------

### Example Event Object

Source: https://github.com/dilettante-trading/polyoxide/blob/main/docs/specs/gamma/events.md

This is an example of the JSON structure for an event object returned by the API.

```json
[
  {
    "id": "evt-123",
    "title": "2025 US Presidential Election",
    "slug": "2025-us-presidential-election",
    "description": "Markets related to the 2025 election.",
    "startDate": "2024-01-01",
    "endDate": "2025-01-20",
    "startDateIso": "2024-01-01T00:00:00Z",
    "endDateIso": "2025-01-20T00:00:00Z",
    "active": true,
    "closed": false,
    "liquidity": 500000.0,
    "volume24hr": 25000.0,
    "negRisk": true,
    "negRiskMarketId": "0xabc...",
    "markets": [],
    "tags": [],
    "series": [],
    "cyom": false
  }
]
```

--------------------------------

### Create API Specs Directories

Source: https://github.com/dilettante-trading/polyoxide/blob/main/docs/plans/2026-03-18-api-specs-implementation.md

Creates the necessary nested directories for API specifications using mkdir -p.

```bash
mkdir -p docs/specs/clob docs/specs/gamma docs/specs/data docs/specs/relay
```

--------------------------------

### Format Code

Source: https://github.com/dilettante-trading/polyoxide/blob/main/CLAUDE.md

Applies the project's standard code formatting to all files in the workspace. Run this before committing.

```bash
cargo fmt --all
```

--------------------------------

### Error Response Example

Source: https://github.com/dilettante-trading/polyoxide/blob/main/docs/specs/data/holders.md

An example of the JSON structure returned for an error response from the Data API.

```json
{"error": "string"}
```

--------------------------------

### Create a DataApi Client

Source: https://github.com/dilettante-trading/polyoxide/blob/main/polyoxide-data/README.md

Instantiate the DataApi client using default settings or customize it with a builder for timeout, pool size, and concurrency.

```rust
use polyoxide_data::DataApi;

// Default configuration
let data = DataApi::new()?;

// Or customize via the builder
let data = DataApi::builder()
    .timeout_ms(30_000)
    .pool_size(10)
    .max_concurrent(8)
    .build()?;

```

--------------------------------

### Initialize RelayClient with Relayer API Key

Source: https://github.com/dilettante-trading/polyoxide/blob/main/polyoxide-relay/README.md

Set up a RelayClient using a static relayer API key and the associated address. This method is suitable for direct API key authentication.

```rust
use polyoxide_relay::{RelayClient, BuilderAccount};

let account = BuilderAccount::with_relayer_api_key(
    "0xprivatekey...",
    "your-relayer-api-key".into(),
    "0xyour-address".into(),
)?;
let client = RelayClient::from_account(account)?;
```

--------------------------------

### Add Polyoxide Crate (User Data Only)

Source: https://github.com/dilettante-trading/polyoxide/blob/main/polyoxide/README.md

Install the Polyoxide crate with only the 'data' feature for user data.

```bash
cargo add polyoxide --no-default-features --features data
```

--------------------------------

### List markets using presets

Source: https://github.com/dilettante-trading/polyoxide/blob/main/polyoxide-cli/README.md

Lists markets using predefined filters such as 'trending', 'top-volume', 'high-liquidity', 'new', or 'competitive'.

```bash
polyoxide gamma markets list --preset trending
```

```bash
polyoxide gamma markets list --preset top-volume
```

```bash
polyoxide gamma markets list --preset high-liquidity
```

```bash
polyoxide gamma markets list --preset new
```

```bash
polyoxide gamma markets list --preset competitive
```

--------------------------------

### Unified Client Usage

Source: https://github.com/dilettante-trading/polyoxide/blob/main/polyoxide/README.md

Demonstrates using the unified Polymarket client to list open markets, retrieve user positions, and place a limit order. Requires environment variables for authentication.

```rust
use polyoxide::prelude::*;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let account = Account::from_env()?;

    let pm = Polymarket::builder(account)
        .chain(Chain::PolygonMainnet)
        .build()?;

    // Gamma: list open markets
    let markets = pm.gamma.markets()
        .list()
        .open(true)
        .limit(10)
        .send()
        .await?;

    // Data: list a user's positions
    let positions = pm.data
        .user("0xabc...")
        .list_positions()
        .limit(5)
        .send()
        .await?;

    for pos in &positions {
        println!("{}: {} shares @ {}", pos.title, pos.size, pos.cur_price);
    }

    // CLOB: place a limit order
    let params = CreateOrderParams {
        token_id: "token_id".into(),
        price: 0.52,
        size: 100.0,
        side: OrderSide::Buy,
        order_type: OrderKind::Gtc,
        post_only: false,
        expiration: None,
        funder: None,
        signature_type: Some(SignatureType::PolyProxy),
    };

    let response = pm.clob.place_order(&params, None).await?;
    println!("Order placed: {:?}", response);

    Ok(())
}
```

--------------------------------

### Send Heartbeat (v1) Response Example

Source: https://github.com/dilettante-trading/polyoxide/blob/main/docs/specs/clob/account.md

Example JSON response for the POST /v1/heartbeats endpoint, returning a new heartbeat ID to be used in subsequent requests.

```json
{"heartbeat_id": "550e8400-e29b-41d4-a716-446655440000"}
```

--------------------------------

### Get Team by ID

Source: https://github.com/dilettante-trading/polyoxide/blob/main/docs/specs/gamma/sports.md

Retrieves specific team information using its unique identifier. This endpoint returns a single Team object, conforming to the same schema as entries from the `GET /teams` endpoint.

```APIDOC
## GET /teams/{id}

### Description
Retrieve team information by team identifier.

### Method
GET

### Endpoint
/teams/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - Team ID

### Response
#### Success Response (200)
Team object (same schema as an entry from `GET /teams`)
```

--------------------------------

### Example Tag Response Object

Source: https://github.com/dilettante-trading/polyoxide/blob/main/docs/specs/gamma/tags.md

An example of a single Tag object returned by the Gamma API. This JSON structure includes details like ID, slug, label, and status flags.

```json
[
  {
    "id": "42",
    "slug": "politics",
    "label": "Politics",
    "forceShow": true,
    "forceHide": false,
    "isCarousel": true,
    "publishedAt": "2024-01-01T00:00:00Z",
    "createdBy": 1,
    "updatedBy": 2,
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-06-01T00:00:00Z"
  }
]
```

--------------------------------

### Individual Gamma Client Usage

Source: https://github.com/dilettante-trading/polyoxide/blob/main/polyoxide/README.md

Example of using the standalone Gamma client for read-only market data. No authentication is required.

```rust
// Read-only Gamma client (no auth required)
use polyoxide::polyoxide_gamma::Gamma;

let gamma = Gamma::builder().build()?;
let events = gamma.events().list().limit(5).send().await?;
```

--------------------------------

### Get a series

Source: https://github.com/dilettante-trading/polyoxide/blob/main/polyoxide-cli/README.md

Retrieves a specific series by its ID.

```bash
polyoxide gamma series get <SERIES_ID>
```

--------------------------------

### Initialize RelayClient from OS Keychain

Source: https://github.com/dilettante-trading/polyoxide/blob/main/polyoxide-relay/README.md

Load authentication credentials directly from the operating system's secure keychain storage. This requires the 'keychain' feature to be enabled.

```rust
use polyoxide_relay::{RelayClient, BuilderAccount};

// Load builder credentials from the OS keychain
let account = BuilderAccount::from_keychain()?;
let client = RelayClient::from_account(account)?;

// Or load relayer API key credentials from the OS keychain
let account = BuilderAccount::from_keychain_relayer_api_key()?;
let client = RelayClient::from_account(account)?;
```

--------------------------------

### data.open_interest

Source: https://github.com/dilettante-trading/polyoxide/blob/main/polyoxide-data/README.md

Gets the current open interest for markets.

```APIDOC
## data.open_interest()

### Description
Retrieves the open interest data for markets.

### Method
`.get()`

### Endpoint
`data.open_interest()`
```

--------------------------------

### GET /oi

Source: https://github.com/dilettante-trading/polyoxide/blob/main/docs/plans/2026-03-18-api-specs-implementation.md

Retrieves the open interest for a specific market.

```APIDOC
## GET /oi

### Description
Retrieves the open interest for a given market.

### Method
GET

### Endpoint
/oi

### Parameters
#### Query Parameters
- **market** (string) - Required - The ID of the market.

### Response
#### Success Response (200)
- **openInterest** (number) - The open interest for the market.

### Request Example
```json
{
  "example": "request body"
}
```

### Response Example
```json
{
  "openInterest": 5000
}
```
```

--------------------------------

### Construct Account Directly

Source: https://github.com/dilettante-trading/polyoxide/blob/main/polyoxide-clob/README.md

Create an Account object by directly providing the private key and API credentials (key, secret, passphrase).

```rust
use polyoxide_clob::{Account, Credentials};

// Direct construction
let credentials = Credentials {
    key: "api_key".to_string(),
    secret: "api_secret".to_string(),
    passphrase: "passphrase".to_string(),
};
let account = Account::new("0x...", credentials)?;
```

--------------------------------

### GET /traded

Source: https://github.com/dilettante-trading/polyoxide/blob/main/docs/plans/2026-03-18-api-specs-implementation.md

Retrieves the total value traded by a user.

```APIDOC
## GET /traded

### Description
Retrieves the total value of assets traded by a user.

### Method
GET

### Endpoint
/traded

### Parameters
#### Query Parameters
- **user** (string) - Required - The user's wallet address.

### Response
#### Success Response (200)
- **traded** (number) - The total value traded by the user.

### Request Example
```json
{
  "example": "request body"
}
```

### Response Example
```json
{
  "traded": 500000.00
}
```
```

--------------------------------

### Configure Gamma client builder

Source: https://github.com/dilettante-trading/polyoxide/blob/main/polyoxide-gamma/README.md

Customize the Gamma client with options like base URL, request timeout, connection pool size, and retry configuration.

```rust
use polyoxide_gamma::Gamma;
use polyoxide_core::RetryConfig;

let gamma = Gamma::builder()
    .base_url("https://gamma-api.polymarket.com")  // default
    .timeout_ms(30_000)           // request timeout
    .pool_size(10)                // HTTP connection pool
    .max_concurrent(4)            // in-flight request cap (prevents Cloudflare 1015)
    .with_retry_config(RetryConfig {
        max_retries: 3,
        initial_backoff_ms: 500,
        max_backoff_ms: 10_000,
    })
    .build()?;

```

--------------------------------

### Get Order

Source: https://github.com/dilettante-trading/polyoxide/blob/main/polyoxide-clob/README.md

Retrieves details for a specific order by its ID.

```APIDOC
## Get Order

### Description
Retrieves the details of a specific order using its unique order ID.

### Method
GET

### Endpoint
/orders/{order_id}

### Parameters
#### Path Parameters
- **order_id** (string) - Required - The ID of the order to retrieve.

### Response
#### Success Response (200)
- **order** (object) - The order object with its details.

### Request Example
```http
GET /orders/0xorder123
```

### Response Example
```json
{
  "order_id": "0xorder123",
  "token_id": "token_id",
  "price": 0.52,
  "size": 100.0,
  "side": "Buy",
  "order_type": "Gtc"
}
```
```

--------------------------------

### Initialize Read-only CLOB Client

Source: https://github.com/dilettante-trading/polyoxide/blob/main/polyoxide-clob/README.md

Create a public CLOB client instance for read-only access to market data. No authentication is required.

```rust
use polyoxide_clob::{Account, Chain, Clob, ClobBuilder, Credentials};

// Read-only client (no authentication, market data only)
let clob = Clob::public();
```

--------------------------------

### Get Midpoint

Source: https://github.com/dilettante-trading/polyoxide/blob/main/polyoxide-clob/README.md

Retrieves the midpoint price for a given token.

```APIDOC
## Get Midpoint

### Description
Retrieves the midpoint price (average of the best bid and ask) for a given token.

### Method
GET

### Endpoint
/markets/{token_id}/midpoint

### Parameters
#### Path Parameters
- **token_id** (string) - Required - The ID of the token.

### Response
#### Success Response (200)
- **midpoint** (number) - The midpoint price.

### Request Example
```http
GET /markets/token_id/midpoint
```

### Response Example
```json
{
  "midpoint": 0.525
}
```
```

--------------------------------

### List markets with custom filters

Source: https://github.com/dilettante-trading/polyoxide/blob/main/polyoxide-cli/README.md

Lists markets with custom filters for limit, offset, status, minimum volume, minimum liquidity, and sorting.

```bash
polyoxide gamma markets list --limit 50 --offset 100 --status closed
```

```bash
polyoxide gamma markets list --volume-min 10000 --liquidity-min 5000 --sort asc
```

--------------------------------

### Get Status

Source: https://github.com/dilettante-trading/polyoxide/blob/main/docs/specs/gamma/INDEX.md

Retrieves the current status of the Gamma API.

```APIDOC
## GET /status

### Description
Retrieves the current status of the Gamma API.

### Method
GET

### Endpoint
/status
```

--------------------------------

### Async User Positions and Leaderboard

Source: https://github.com/dilettante-trading/polyoxide/blob/main/polyoxide-py/README.md

Example of fetching user positions and leaderboard data asynchronously using the DataApi. Requires an active asyncio event loop.

```python
import asyncio
from polyoxide import DataApi

async def main():
    data = DataApi()

    # Leaderboard
    leaders = await data.leaderboard().get(limit=10, time_period="WEEK")
    for t in leaders:
        print(t.username, t.pnl)

    # User positions
    positions = await data.user("0xADDRESS").list_positions(limit=5)
    for p in positions:
        print(p.title, p.size)

asyncio.run(main())
```

--------------------------------

### GET /live-volume

Source: https://github.com/dilettante-trading/polyoxide/blob/main/docs/plans/2026-03-18-api-specs-implementation.md

Retrieves the live trading volume for a specific ID.

```APIDOC
## GET /live-volume

### Description
Retrieves the live trading volume for a specified ID.

### Method
GET

### Endpoint
/live-volume

### Parameters
#### Query Parameters
- **id** (integer) - Required - The ID for which to retrieve live volume (must be ≥ 1).

### Response
#### Success Response (200)
- **volume** (number) - The live trading volume.

### Request Example
```json
{
  "example": "request body"
}
```

### Response Example
```json
{
  "volume": 12000.50
}
```
```

--------------------------------

### Sync Market Data Fetching

Source: https://github.com/dilettante-trading/polyoxide/blob/main/polyoxide-py/README.md

Example of fetching the latest open markets synchronously using the GammaSync client. This method blocks the GIL while waiting for the response.

```python
from polyoxide import GammaSync

gamma = GammaSync()
markets = gamma.markets().list(limit=5, open=True)
for m in markets:
    print(f"{m.question}  --  {m.slug}")
```

--------------------------------

### GET /value

Source: https://github.com/dilettante-trading/polyoxide/blob/main/docs/plans/2026-03-18-api-specs-implementation.md

Retrieves the total value of a user's positions.

```APIDOC
## GET /value

### Description
Retrieves the total current value of all of a user's positions.

### Method
GET

### Endpoint
/value

### Parameters
#### Query Parameters
- **user** (string) - Required - The user's wallet address.

### Response
#### Success Response (200)
- **value** (number) - The total value of the user's positions.

### Request Example
```json
{
  "example": "request body"
}
```

### Response Example
```json
{
  "value": 150000.75
}
```
```

--------------------------------

### Get Builder Trades

Source: https://github.com/dilettante-trading/polyoxide/blob/main/docs/plans/2026-03-18-api-specs-implementation.md

Retrieves a list of trades specifically for builders.

```APIDOC
## GET /builder-trades

### Description
Retrieves a list of trades for builders.

### Method
GET

### Endpoint
/builder-trades

### Response
#### Success Response
Returns a builder trade list.
```

--------------------------------

### List tags

Source: https://github.com/dilettante-trading/polyoxide/blob/main/polyoxide-cli/README.md

Lists all available tags.

```bash
polyoxide gamma tags list
```

--------------------------------

### Get Server Time

Source: https://github.com/dilettante-trading/polyoxide/blob/main/polyoxide-clob/README.md

Retrieves the current time from the CLOB server.

```APIDOC
## Get Server Time

### Description
Retrieves the current server time from the CLOB API.

### Method
GET

### Endpoint
/health/server_time

### Response
#### Success Response (200)
- **server_time** (string) - The current server time in ISO 8601 format.

### Request Example
```http
GET /health/server_time
```

### Response Example
```json
{
  "server_time": "2023-11-15T10:30:00Z"
}
```
```

--------------------------------

### Check Safe Deployment using cURL

Source: https://github.com/dilettante-trading/polyoxide/blob/main/docs/specs/relay/transactions.md

Example using cURL to check if a Safe address is deployed. The response is piped to `jq` for pretty-printing.

```bash
# Check if an address has a deployed Safe
curl -s 'https://relayer-v2.polymarket.com/deployed?address=0xFeA4cB3dD4ca7CefD3368653B7D6FF9BcDFca604' | jq .

```

--------------------------------

### Get Builder Trades

Source: https://github.com/dilettante-trading/polyoxide/blob/main/polyoxide-clob/README.md

Retrieves trades generated through the builder interface.

```APIDOC
## Get Builder Trades

### Description
Retrieves a list of trades that were executed via the builder interface.

### Method
GET

### Endpoint
/account/builder_trades

### Response
#### Success Response (200)
- **trades** (array) - A list of trade objects generated by the builder.

### Request Example
```http
GET /account/builder_trades
```

### Response Example
```json
[
  {
    "trade_id": "0xtrade_builder_1",
    "timestamp": "1700002000",
    "market": "0x456",
    "side": "Sell",
    "price": 0.53,
    "size": 5.0
  }
]
```
```

--------------------------------

### Get USDC Balance

Source: https://github.com/dilettante-trading/polyoxide/blob/main/polyoxide-clob/README.md

Retrieves the user's balance of USDC.

```APIDOC
## Get USDC Balance

### Description
Retrieves the user's current balance of USDC.

### Method
GET

### Endpoint
/account/usdc_balance

### Response
#### Success Response (200)
- **usdc_balance** (number) - The user's balance of USDC.

### Request Example
```http
GET /account/usdc_balance
```

### Response Example
```json
{
  "usdc_balance": 1500.75
}
```
```

--------------------------------

### Configure RelayClient using Builder Pattern

Source: https://github.com/dilettante-trading/polyoxide/blob/main/polyoxide-relay/README.md

Construct a RelayClient instance with specific configurations like wallet type and chain ID using a fluent builder API. Defaults to Polygon mainnet.

```rust
use polyoxide_relay::{RelayClient, BuilderAccount, BuilderConfig, WalletType};

let config = BuilderConfig::new("key".into(), "secret".into(), None);
let account = BuilderAccount::new("0xprivatekey...", Some(config))?;

let client = RelayClient::builder()? 
    .with_account(account)
    .wallet_type(WalletType::Safe)
    .chain_id(137)               // Polygon mainnet (default)
    .max_concurrent(2)
    .build()?;
```

--------------------------------

### Get comment by ID

Source: https://github.com/dilettante-trading/polyoxide/blob/main/polyoxide-gamma/README.md

Fetch a specific comment using its ID.

```rust
let comment = gamma.comments().get("comment_id").send().await?;

```

--------------------------------

### Load BuilderAccount from Keychain

Source: https://github.com/dilettante-trading/polyoxide/blob/main/docs/plans/2026-04-16-keychain-credentials-implementation.md

Loads a BuilderAccount from the OS keychain using the 'polyoxide-relay' service. It retrieves the private key, and optionally API key, secret, and passphrase. Handles cases where API credentials might be missing.

```rust
    /// Load account from the OS keychain with builder API credentials.
    ///
    /// Reads from the `polyoxide-relay` keychain service:
    /// - `private_key`: Hex-encoded private key (required)
    /// - `api_key`, `api_secret`: Builder API credentials (optional — if `api_key` is
    ///   not found, the account is created without auth config)
    /// - `passphrase`: Builder API passphrase (optional)
    #[cfg(feature = "keychain")]
    pub fn from_keychain() -> Result<Self, RelayError> {
        use polyoxide_core::keychain;
        const SERVICE: &str = "polyoxide-relay";

        let private_key = keychain::get(SERVICE, "private_key")
            .map_err(|e| RelayError::Api(format!("Keychain error for private_key: {e}")))?;

        let config = match keychain::get(SERVICE, "api_key") {
            Ok(key) => {
                let secret = keychain::get(SERVICE, "api_secret").map_err(|e| {
                    RelayError::Api(format!("Keychain error for api_secret: {e}"))
                })?;
                let passphrase = keychain::get(SERVICE, "passphrase").ok();
                Some(BuilderConfig::new(key, secret, passphrase))
            }
            Err(polyoxide_core::KeychainError::NotFound { .. }) => None,
            Err(e) => return Err(RelayError::Api(format!("Keychain error: {e}"))),
        };

        Self::new(private_key, config)
    }
```

--------------------------------

### Get Tag by ID

Source: https://github.com/dilettante-trading/polyoxide/blob/main/docs/specs/gamma/tags.md

Retrieves a single tag by its unique identifier.

```APIDOC
## GET /tags/{id}

### Description
Get a single tag by its ID.

### Method
GET

### Endpoint
/tags/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - Tag ID

### Response
#### Success Response (200)
- **Tag object**
```

--------------------------------

### List open markets

Source: https://github.com/dilettante-trading/polyoxide/blob/main/polyoxide-cli/README.md

Lists open markets with default filters for limit, offset, and status. Defaults are limit=20, offset=0, active=true, status=open.

```bash
polyoxide gamma markets list
```

--------------------------------

### Get Traded Status

Source: https://github.com/dilettante-trading/polyoxide/blob/main/docs/specs/data/positions.md

Returns whether a user has ever traded.

```APIDOC
## GET /traded

### Description
Returns whether a user has ever traded.

### Method
GET

### Endpoint
/traded

### Parameters
#### Query Parameters
- **user** (Address) - Required - User wallet address

### Response
#### Success Response (200)
- **Traded**
```

--------------------------------

### Verify Keychain Feature with Cargo Check

Source: https://github.com/dilettante-trading/polyoxide/blob/main/docs/plans/2026-04-16-keychain-credentials-implementation.md

Run this command to check if the polyoxide crate builds successfully with the 'clob' and 'keychain' features enabled.

```bash
cargo check -p polyoxide --features "clob,keychain"
```

--------------------------------

### GET /v1/builders/volume

Source: https://github.com/dilettante-trading/polyoxide/blob/main/docs/plans/2026-03-18-api-specs-implementation.md

Retrieves the trading volume for builders, with filtering by time period.

```APIDOC
## GET /v1/builders/volume

### Description
Retrieves the trading volume data for builders, allowing filtering by a specified time period.

### Method
GET

### Endpoint
/v1/builders/volume

### Parameters
#### Query Parameters
- **timePeriod** (string) - Optional - The time period for the volume data. Allowed values: DAY, WEEK, MONTH, ALL.

### Response
#### Success Response (200)
- **user** (string) - The builder's address.
- **volume** (number) - The total trading volume for the builder.

### Request Example
```json
{
  "example": "request body"
}
```

### Response Example
```json
{
  "user": "0xBuilder123",
  "volume": 150000
}
```
```

--------------------------------

### Get Order Scoring Status

Source: https://github.com/dilettante-trading/polyoxide/blob/main/docs/plans/2026-03-18-api-specs-implementation.md

Retrieves the current status of order scoring.

```APIDOC
## GET /order-scoring

### Description
Retrieves the current status of order scoring.

### Method
GET

### Endpoint
/order-scoring

### Response
#### Success Response
Returns the order scoring status.
```