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

# Prediction API

> Prediction-market historical ticks, reference data, and full-text search over base events, events, and contracts.

The **Prediction API** is the read API for prediction-market data: tick-level YES/NO price history, the instrument catalogue, and full-text search across it. Use it to discover contracts, enumerate the outcomes under an event, and back charts or models with historical prices.

## Environments

These endpoints are available in two environments, selectable from the server dropdown in the playground on each endpoint page:

| Environment | Base URL                     |
| ----------- | ---------------------------- |
| Production  | `https://api.aries.com`      |
| Staging     | `https://api.tradearies.dev` |

Paths, parameters, and response shapes are identical in both. Staging carries its own catalogue and tick history, so symbols and event IDs will not match production.

***

## The three levels

Everything in this API is organized the same way, from broadest to narrowest:

| Level          | What it is                                    | Example ID     |
| -------------- | --------------------------------------------- | -------------- |
| **Base event** | A series of recurring questions               | `UNR`          |
| **Event**      | One real-world question within the series     | `UNR_0822`     |
| **Contract**   | One tradable outcome or strike under an event | `UNR_0822_3.5` |

A contract's `symbol` is the key used everywhere else: it is what you pass to the historical-data endpoints, and what search returns.

## Historical data

| Endpoint                                                                   | Description                                                                     |
| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| [**Get historical ticks**](/api-reference/predictions/get-history)         | Return YES/NO price history for a single contract over an optional time window. |
| [**Batch historical ticks**](/api-reference/predictions/get-history-batch) | Retrieve ticks for up to 5 symbols in one request, each with its own window.    |

## Reference data and search

| Endpoint                                                                  | Description                                                           |
| ------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| [**Search prediction market**](/api-reference/predictions/search)         | Full-text search returning hits as contracts, events, or base events. |
| [**Get event contracts**](/api-reference/predictions/get-event-contracts) | Return one event together with every contract under it.               |
| [**Get base event**](/api-reference/predictions/get-base-event)           | Return a base event with its events and each event's contracts.       |

***

## Working with this API

### Prices are decimal strings

`yesPrice`, `noPrice`, and `tickSize` are exact decimals serialized as JSON **strings** (`"0.54"`, not `0.54`). Parse them with a decimal type. Reading them into a binary float loses precision at the tick sizes these contracts trade at.

### Search trails the catalogue

Search results come from an index that lags the catalogue by seconds. Use a hit's `symbol` as a key, then read anything that must be current — `state`, `tradable` — from [Get Event Contracts](/api-reference/predictions/get-event-contracts). Do not act on a hit's own fields.

### Venue times carry no zone

`expectedPayoutTime`, `expectedLastTradeTime`, and `expectedResolutionTime` are venue **wall-clock** times. The upstream feed carries no time zone, so the trailing `Z` is a label rather than a conversion — do not shift these into local time.

### Response envelope

Every response uses the same envelope. On success:

```json theme={null}
{
  "success": true,
  "data": { }
}
```

On failure, `success` is `false` and `error` is a structured object with a categorical `type` (`VALIDATION`, `NOT_FOUND`, `INTERNAL`, `EXTERNAL_SERVICE`, …), a machine-readable `code`, and a human-readable `message`. Branch on `type` and `code`; message text is not fixed.

```json theme={null}
{
  "success": false,
  "error": {
    "type": "NOT_FOUND",
    "code": "EVENT_NOT_FOUND",
    "message": "string"
  }
}
```

A `502` means the upstream data store or search index was unavailable — retry it; it does not indicate a bad request.

## Common uses

* Discover contract symbols and event IDs with search before pulling historical ticks.
* Enumerate every strike under an event, or the full event/contract tree under a base event.
* Pull YES/NO tick history for one or many contracts to drive charting and modeling workflows.
* Re-read `state` and `tradable` from the catalogue before acting on a symbol found through search.