> ## Documentation Index
> Fetch the complete documentation index at: https://docs.counsel.markets/llms.txt
> Use this file to discover all available pages before exploring further.

# counsel API v1 Reference: Parimutuel Markets on XRPL

> Complete reference for counsel API v1. Read-only, no auth, all responses JSON. Seven endpoints: markets, bet construction, accounts, and leaderboard.

The counsel API v1 is a public, read-only HTTP API for the counsel parimutuel prediction market on the XRP Ledger. It exposes live market state, indicative odds, unsigned bet transaction construction, account positions, and leaderboard data. No API key, no OAuth, no registration, every response is plain JSON. The API is consumed by the counsel web app, bots, and third-party integrators alike.

## Base URL

The API is reachable at two equivalent base URLs:

```
https://api.counsel.markets
https://counsel.markets/api/v1
```

All paths below are relative to either base. The canonical subdomain (`api.counsel.markets`) is preferred for programmatic clients; the path-based form (`/api/v1`) is provided for convenience.

## Authentication

None. All endpoints are publicly accessible without credentials. No `Authorization` header, no API key, no session cookie.

## Response Format

All responses are `application/json`. Successful responses return HTTP `200` with a JSON object. Collection responses include a top-level `generated_at` field (ISO 8601 timestamp) indicating when the indexer snapshot was produced.

## Error Format

Errors return a non-`2xx` HTTP status code and a JSON body. Single-error responses use:

```json theme={null}
{ "error": "market not found" }
```

Validation failures (e.g. bad query parameters) return an array:

```json theme={null}
{ "errors": ["invalid account address", "amount must be positive"] }
```

| HTTP Status | Meaning                                       |
| ----------- | --------------------------------------------- |
| `400`       | Bad request, invalid parameters               |
| `403`       | Forbidden, address on the compliance denylist |
| `404`       | Resource not found                            |
| `500`       | Internal indexer or server error              |

## Rate Limiting

No hard rate limits are published. The API is backed by a live XRPL indexer; treat it like any shared public API and avoid polling at intervals shorter than a few seconds. If you are running a bot, cache the market list and only re-fetch on a reasonable schedule.

## Endpoints

| Method | Path                           | Description                                            |
| ------ | ------------------------------ | ------------------------------------------------------ |
| `GET`  | `/markets`                     | All public markets with live pools and indicative odds |
| `GET`  | `/markets/:id`                 | Single market live state, outcomes, and bet caps       |
| `GET`  | `/markets/:id/bet-intent`      | Unsigned XRPL Payment + projected odds post-stake      |
| `GET`  | `/accounts/:address/positions` | An account's stakes by market and outcome              |
| `GET`  | `/accounts/:address/feed`      | A leader's recent bets (powers copy trading)           |
| `GET`  | `/accounts/:address/profile`   | Stats, cumulative volume series, positions, rank       |
| `GET`  | `/leaderboard`                 | SourceTag-attributed volume and active accounts        |

## Common Response Fields

**`generated_at`**, present on all list responses. ISO 8601 string representing the moment the indexer snapshot was generated. Use this to detect stale data; under normal conditions it should be within a few seconds of the current time.

**`source_tag`**, present on `/markets` and `/markets/:id/bet-intent`. The SourceTag counsel uses to attribute on-chain volume. Do not strip it from transactions you construct or sign.

<CardGroup cols={2}>
  <Card title="List Markets" icon="list" href="/api/markets/list">
    Fetch all public markets with live pool totals and indicative odds.
  </Card>

  <Card title="Get Market" icon="chart-bar" href="/api/markets/get">
    Fetch a single market by ID, including bet caps.
  </Card>

  <Card title="Bet Intent" icon="pen" href="/api/markets/bet-intent">
    Build an unsigned XRPL Payment ready to sign and submit.
  </Card>

  <Card title="Overview" icon="book" href="/api/overview">
    Error codes, rate limits, and base URL reference.
  </Card>
</CardGroup>