> For the complete documentation index, see [llms.txt](https://docs.polyscout.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.polyscout.io/developers/api-access.md).

# API Access

## Base URL and Versioning

The Polyscout API is available at the following base URL:

```json
https://api.polyscout.io
```

All API endpoints are served under versioned paths. The current version is `/v1`.

All requests and responses use JSON and must include the appropriate `Content-Type` header when a body is present.

```http
Content-Type: application/json
```

## Authentication Header

All `/v1/*` endpoints require an API key passed using the standard `Authorization` header.

```json
Authorization: Bearer <POLYSCOUT_USER_API_KEY>
```

API keys are issued per user and can be generated through the Polyscout Telegram bot using the `/api` command. Each key is tied to a specific Polyscout user account and controls access to that user’s wallets, strategies, and executions.

If the header is missing or the key is invalid, the API returns a `401 UNAUTHORIZED` response.

## Request IDs

Requests may optionally include a request identifier to help with tracing and debugging.

```python
x-request-id: <your-request-id>
```

If this header is not provided, Polyscout automatically generates one. Every response includes an `x-request-id` header so requests can be correlated in logs.

## Idempotency

For POST requests that create or modify state, Polyscout supports idempotency to safely handle retries.

Clients may include an `Idempotency-Key` header with a unique value per logical request.

```json
Idempotency-Key: <unique-key>
```

If the same request is retried with the same idempotency key, Polyscout returns the original response. If the same key is reused with a different payload, the API returns a `409 IDEMPOTENCY_KEY_REUSED` error.

If a request with the same idempotency key is still being processed, the API returns `409 IDEMPOTENCY_IN_PROGRESS` and includes a `Retry-After` header indicating when to retry.

## Pagination

List endpoints support offset-based pagination using `cursor` and `limit` query parameters.

The `cursor` parameter is a zero-based offset. The `limit` parameter controls page size, with a maximum of 25 items per request.

Responses include a `next_cursor` field when additional results are available. When `next_cursor` is `null`, there are no more results.

## Rate Limiting

Authenticated endpoints apply rate limits on a per-user and per-IP basis.

Rate limit information is returned via standard headers:

* `x-ratelimit-limit` indicates the maximum burst size
* `x-ratelimit-remaining` shows how many requests remain in the current window
* `x-ratelimit-reset` indicates when the limit will reset

If a client exceeds the rate limit, the API returns `429 RATE_LIMITED` and includes a `Retry-After` header specifying how long to wait before retrying.

## Error Format

All errors are returned in a consistent JSON structure.

```json
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Missing or invalid trade_amount",
    "details": {
      "optional": "context"
    }
  }
}
```

Common error codes include `UNAUTHORIZED`, `FORBIDDEN`, `BAD_REQUEST`, `NOT_FOUND`, `RATE_LIMITED`, and `INTERNAL`.