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

# Conventions

The API is internally consistent about units, and that consistency is the thing most likely to bite an integration that assumes otherwise. Nothing is a floating-point currency amount, and nothing is a percentage.

## Numbers

| Convention            | Type                 | Range        | Example                 |
| --------------------- | -------------------- | ------------ | ----------------------- |
| Prices, odds, spreads | Integer basis points | 0 to 10000   | `3157` is 31.57 percent |
| Money                 | Integer cents        | Non-negative | `79` is USD 0.79        |
| Shares                | Float                | Non-negative | `4.7824` shares         |

Basis points appear in every field suffixed `Bps`: `yesPriceBps`, `noPriceBps`, `spreadBps`, `bestBidBps`, `bestAskBps`, `midpointBps`, `lastTradePriceBps`, `priceBps` and `currentOddsBps`. Divide by 100 for a percentage, or by 10000 for a probability.

Cents appear in every field suffixed `Cents`: `volumeCents`, `valueCents`, `amountCents`, `totalVolumeCents`, `minBetCents`, `maxBetCents`, `totalPayoutCents` and the exposure limits. These are integers, so no rounding is required to display them, and none should be introduced.

{% hint style="danger" %}
**Shares are floats, prices and money are not**

`shares` is a genuine float and can carry many decimal places, as in `2.444987`. Do not coerce it to an integer, and do not assume a fixed number of decimal places. Conversely, do not introduce floating-point arithmetic into cent or basis-point values; keep them as integers until the moment of display.
{% endhint %}

## Timestamps

Every time field uses the `Time` scalar, serialised as ISO 8601 with an explicit UTC designator.

```
2026-08-07T23:59:59Z
2026-08-07T11:37:05.024487Z
```

Note that fractional seconds appear on some values and not others, so parse rather than pattern-match. When passing a `Time` argument, such as the `since` parameter on `priceHistory`, the same format is expected.

## Pagination

Market and trade collections use Relay-style cursor pagination, in both directions.

| Argument | Purpose                                |
| -------- | -------------------------------------- |
| `first`  | Number of items to take from the start |
| `after`  | Cursor to continue forward from        |
| `last`   | Number of items to take from the end   |
| `before` | Cursor to continue backward from       |

Every connection returns `edges`, a `pageInfo` object with `hasNextPage`, `hasPreviousPage`, `startCursor` and `endCursor`, and a `totalCount`.

```graphql
query Page($input: MarketsInput) {
  markets(input: $input) {
    totalCount
    pageInfo { hasNextPage endCursor }
    edges { node { id question } }
  }
}
```

To walk the collection, pass the previous `endCursor` as `after` and stop when `hasNextPage` is false.

{% hint style="info" %}
**Cursors are opaque**

The cursor is an encoded record of position and sort value. It is not a market identifier, it is not stable across a change of sort order, and it should not be parsed, stored long-term or constructed by hand. Treat it as a token you received and hand back unchanged.
{% endhint %}

## Enumerations

Enumerated values are worth reading in full, because several carry more states than a naive open-or-resolved model would expect.

**`MarketStatus`** has nine values: `OPEN`, `PENDING_RESOLUTION`, `RESOLVED`, `RESOLVED_YES`, `RESOLVED_NO`, `RESOLVED_UNCERTAIN`, `RESOLUTION_FAILED`, `CANCELLED` and `PENDING_BLOCKCHAIN`. A client that branches only on `OPEN` and `RESOLVED` will mishandle the rest, and `RESOLUTION_FAILED` and `RESOLVED_UNCERTAIN` in particular deserve explicit handling in any interface that shows a user what happened to their position.

**`BetOutcome`** has three values: `YES`, `NO` and `CANCELLED`.

**`MarketSort`** offers `CREATED_AT_DESC`, `CREATED_AT_ASC`, `VOLUME_DESC`, `VOLUME_ASC`, `RESOLUTION_DATE_ASC` and `RESOLUTION_DATE_DESC`.

**`OrderSide`** is `BUY` or `SELL`. **`ResolutionOutcome`** is `RESOLVED_YES`, `RESOLVED_NO` or `CANCELLED`.

## Errors

Errors arrive with HTTP 200 and a standard GraphQL `errors` array. Checking the status code is not sufficient; check for the presence of `errors`.

An invalid argument returns a message and the field path, with a null value for that field.

```json
{
  "errors": [
    { "message": "invalid market ID: invalid UUID length: 13", "path": ["market"] }
  ],
  "data": { "market": null }
}
```

A request to a protected field without credentials returns a null data payload.

```json
{
  "errors": [{ "message": "UNAUTHORIZED", "path": ["claimablePositions"] }],
  "data": null
}
```

{% hint style="warning" %}
**Errors carry no machine-readable code**

Each error provides `message` and `path` only. There is no `extensions` object and no stable error code, so programmatic handling has to match on message strings, which are liable to change. Match on `UNAUTHORIZED` for the authentication case, treat everything else as opaque, and log the full message rather than a category.
{% endhint %}

Because GraphQL resolves fields independently, a partial success is normal: a request for several fields may return data for some and errors for others. Always read both keys.

## Next

[Market Data](broken://pages/5fb68f703e140d02157805616bc295e4610f0050) covers the market, category and topic queries in detail.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.prophetmarket.ai/api/conventions.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.