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

# Overview

### About PRED

PRED is a fully decentralized prediction market platform built on Base (Ethereum L2), enabling users to trade on real-world events with LONG and SHORT positions—similar to perpetual futures trading.

**LONG positions** profit when the event occurs (YES outcome), while **SHORT positions** profit when it doesn't (NO outcome). PRED uses a decentralized architecture where users maintain full custody of their funds through Gnosis Safe proxy wallets, requiring cryptographic signatures (EIP-712) for every order.

Each user trades through their own Gnosis Safe proxy wallet. In the CLOB flow, creating credentials creates the account only; Safe creation and trading approval are separate user-signed steps. Fund the Safe with supported USDC on Base, not the EOA.

### Choose one authentication flow

| Integration                  | Account/API authentication                                        | Order authorization                      | Start here                         |
| ---------------------------- | ----------------------------------------------------------------- | ---------------------------------------- | ---------------------------------- |
| Aggregator / partner         | L1 for credential creation/recovery; per-user L2 HMAC for `/clob` | Each user's PRED EIP-712 Order signature | Builder / Aggregator CLOB          |
| Existing JWT client / Go SDK | Login with `X-API-Key`, then Bearer JWT                           | PRED EIP-712 Order signature             | Ordinary JWT getting started below |
| Public market data           | None; use unprefixed `/api/v1/market-discovery/*` and orderbook   | Not applicable                           | Market Discovery                   |

`X-API-Key` (ordinary login), `X-Aggregator-API-Key` (new account creation), and `PRED_API_KEY` (one user's L2 credential) are different keys and are not interchangeable.

### Ordinary JWT getting started (not the aggregator flow)

**Step 1:** Call `POST /api/v1/auth/login-with-signature` with `X-API-Key` header and EIP-712 CreateProxy signature. Save from the response:

* `access_token`
* `refresh_token`
* `proxy_wallet_addr`
* `user_id`
* `is_enabled_trading`

**Step 1b (ordinary JWT flow, if `is_enabled_trading` is `false` or missing):** (a) `POST /api/v1/user/safe-approval/prepare` with `{}`; the Safe is resolved from the user; (b) sign the prepared `transactionHash` using raw secp256k1 (no EIP-191 prefix); (c) `POST /api/v1/user/safe-approval/execute` with `{ signature, data }`; (d) log in again for a JWT with `is_enabled_trading=true`. CLOB clients do not log in again; check account-status before trading. See **Builder / Aggregator CLOB**.

**Before trading:** discover valid parent/child market IDs from `GET /api/v1/market-discovery/discover?verbose=true&limit=50&offset=0`. Page with `offset += limit` until `data.total` is exhausted. Use only rows where `parent_market_data.status == "active"` and the child `markets[].status == "active"`; treat terminal child statuses such as `resolved` or `redeemed` as not quote/trade eligible. `verbose=true` is required for the fields most trading clients need: `parent_market_data.parent_market_id`, `parent_market_data.type_reference_id`, `parent_market_data.contract_address`, `parent_market_data.parent_market_type`, `parent_market_data.parent_market_family`, and fixture metadata. The order contract for signatures must come from the discovered parent row.

**Step 2:** `GET /api/v1/order/{parentMarketID}/orderbook/{marketID}` — prices in cents, sizes in shares.

**Step 3:** `POST /api/v1/order/{parentMarketID}/place` with EIP-712 Order signature. Amount: Long = `(price*qty)/100`, Short = `((100-price)*qty)/100`.

**Step 4:** `GET /api/v1/portfolio/positions`

**Step 5:** `GET /api/v1/order/{parentMarketID}/open-orders` (recommended, real-time)

**Step 6:** `DELETE /api/v1/order/{parentMarketID}/cancel`

For login signature details (CreateProxy domain, message, normalization), see **Authentication**.

For what `parent_market_id` and `market_id` are and how to obtain them, see **Market Discovery**.

### X-API-Key

The `X-API-Key` header is **required** to use PRED's login-with-signature endpoint (`POST /api/v1/auth/login-with-signature`). Please reach out to PRED to request an API key.

### API configuration

| Setting                           | Value                                                                |
| --------------------------------- | -------------------------------------------------------------------- |
| Public API host                   | `https://www.pred.app`                                               |
| CLOB base URL                     | `https://www.pred.app/clob`                                          |
| Chain                             | Base, chain ID `8453`                                                |
| Supported deposit asset           | Native USDC on Base only                                             |
| USDC token contract               | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`                         |
| Chain type in ordinary login body | `base`                                                               |
| CreateProxy verifying contract    | `0xA077e7aaBF2e3c0155F83789e95f46602D03F7f0`                         |
| Order verifying contract          | `parent_market_data.contract_address` for the selected parent market |

OpenAPI paths already include `/clob`; do not append it to the server URL again. Market discovery and public orderbooks use the unprefixed `/api/v1/...` paths.

**Order signatures:** obtain the verifying contract from `GET /api/v1/market-discovery/discover?verbose=true&limit=50&offset=0` or `GET /api/v1/market-discovery/parents/{parentMarketID}`. Different parent markets can use different contracts; do not substitute the CreateProxy factory or assume a single exchange.

### Browser API access

Direct browser calls require CORS approval for the calling origin, methods and headers. Contact PRED to confirm origin access. A CORS error is distinct from an authentication error. Authenticated calls require freshly computed signatures and timestamps; entering static headers into an API explorer does not generate them.

### Deposits — USDC on Base only

**Only native USDC on Base (chain ID `8453`) is supported for deposits.** The supported token contract is `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`, as listed in [Circle's USDC contract reference](https://developers.circle.com/stablecoins/usdc-contract-addresses). USDC on other networks, bridged USDbC, USDT, ETH, and other tokens are not supported deposit assets. Unsupported transfers will not fund the user's PRED trading balance; recovery is not guaranteed.

The **deposit address is the user's own Safe proxy wallet**, not the signing EOA, partner wallet, or USDC token contract. For CLOB, retrieve it from the top-level `proxy_wallet_address` returned by `GET /clob/api/v1/user/account-status` using that user's L2 credentials. For ordinary JWT login, use `data.proxy_wallet_addr`. An empty address means Safe creation has not completed; do not send funds.

Deposit by transferring the supported USDC token on Base to that Safe. There is no CLOB deposit-submission API; an account-status or balance request does not transfer funds. See **Builder / Aggregator CLOB → Deposits** for address retrieval, the transfer contract, and confirmation through `GET /clob/api/v1/portfolio/balance`.

## Overview — About PRED, getting started

> See the \*\*Overview\*\* tag description for: About PRED, getting started, X-API-Key, testing APIs, and environment configuration.<br>

```json
{"openapi":"3.1.0","info":{"title":"PRED Trading Platform API","version":"1.2.0"},"tags":[{"name":"Overview","description":"## About PRED\n\nPRED is a fully decentralized prediction market platform built on Base (Ethereum L2), enabling users to trade on real-world events with LONG and SHORT positions—similar to perpetual futures trading.\n\n**LONG positions** profit when the event occurs (YES outcome), while **SHORT positions** profit when it doesn't (NO outcome). PRED uses a decentralized architecture where users maintain full custody of their funds through Gnosis Safe proxy wallets, requiring cryptographic signatures (EIP-712) for every order.\n\nEach user trades through their own Gnosis Safe proxy wallet. In the CLOB flow, creating\ncredentials creates the account only; Safe creation and trading approval are separate\nuser-signed steps. Fund the Safe with supported USDC on Base, not the EOA.\n\n## Choose one authentication flow\n\n| Integration | Account/API authentication | Order authorization | Start here |\n|-------------|----------------------------|---------------------|------------|\n| Aggregator / partner | L1 for credential creation/recovery; per-user L2 HMAC for `/clob` | Each user's PRED EIP-712 Order signature | Builder / Aggregator CLOB |\n| Existing JWT client / Go SDK | Login with `X-API-Key`, then Bearer JWT | PRED EIP-712 Order signature | Ordinary JWT getting started below |\n| Public market data | None; use unprefixed `/api/v1/market-discovery/*` and orderbook | Not applicable | Market Discovery |\n\n`X-API-Key` (ordinary login), `X-Aggregator-API-Key` (new account creation), and\n`PRED_API_KEY` (one user's L2 credential) are different keys and are not interchangeable.\n\n## Ordinary JWT getting started (not the aggregator flow)\n\n**Step 1:** Call `POST /api/v1/auth/login-with-signature` with `X-API-Key` header and EIP-712 CreateProxy signature. Save from the response:\n- `access_token`\n- `refresh_token`\n- `proxy_wallet_addr`\n- `user_id`\n- `is_enabled_trading`\n\n**Step 1b (ordinary JWT flow, if `is_enabled_trading` is `false` or missing):** (a) `POST /api/v1/user/safe-approval/prepare` with `{}`; the Safe is resolved from the user; (b) sign the prepared `transactionHash` using raw secp256k1 (no EIP-191 prefix); (c) `POST /api/v1/user/safe-approval/execute` with `{ signature, data }`; (d) log in again for a JWT with `is_enabled_trading=true`. CLOB clients do not log in again; check account-status before trading. See **Builder / Aggregator CLOB**.\n\n**Before trading:** discover valid parent/child market IDs from `GET /api/v1/market-discovery/discover?verbose=true&limit=50&offset=0`. Page with `offset += limit` until `data.total` is exhausted. Use only rows where `parent_market_data.status == \"active\"` and the child `markets[].status == \"active\"`; treat terminal child statuses such as `resolved` or `redeemed` as not quote/trade eligible. `verbose=true` is required for the fields most trading clients need: `parent_market_data.parent_market_id`, `parent_market_data.type_reference_id`, `parent_market_data.contract_address`, `parent_market_data.parent_market_type`, `parent_market_data.parent_market_family`, and fixture metadata. The order contract for signatures must come from the discovered parent row.\n\n**Step 2:** `GET /api/v1/order/{parentMarketID}/orderbook/{marketID}` — prices in cents, sizes in shares.\n\n**Step 3:** `POST /api/v1/order/{parentMarketID}/place` with EIP-712 Order signature. Amount: Long = `(price*qty)/100`, Short = `((100-price)*qty)/100`.\n\n**Step 4:** `GET /api/v1/portfolio/positions`\n\n**Step 5:** `GET /api/v1/order/{parentMarketID}/open-orders` (recommended, real-time)\n\n**Step 6:** `DELETE /api/v1/order/{parentMarketID}/cancel`\n\nFor login signature details (CreateProxy domain, message, normalization), see **Authentication**.\n\nFor what `parent_market_id` and `market_id` are and how to obtain them, see **Market Discovery**.\n\n## X-API-Key\n\nThe `X-API-Key` header is **required** to use PRED's login-with-signature endpoint (`POST /api/v1/auth/login-with-signature`). Please reach out to PRED to request an API key.\n\n## API configuration\n\n| Setting | Value |\n|---------|-------|\n| Public API host | `https://www.pred.app` |\n| CLOB base URL | `https://www.pred.app/clob` |\n| Chain | Base, chain ID `8453` |\n| Supported deposit asset | Native USDC on Base only |\n| USDC token contract | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` |\n| Chain type in ordinary login body | `base` |\n| CreateProxy verifying contract | `0xA077e7aaBF2e3c0155F83789e95f46602D03F7f0` |\n| Order verifying contract | `parent_market_data.contract_address` for the selected parent market |\n\nOpenAPI paths already include `/clob`; do not append it to the server URL again.\nMarket discovery and public orderbooks use the unprefixed `/api/v1/...` paths.\n\n**Order signatures:** obtain the verifying contract from\n`GET /api/v1/market-discovery/discover?verbose=true&limit=50&offset=0` or\n`GET /api/v1/market-discovery/parents/{parentMarketID}`. Different parent markets can use\ndifferent contracts; do not substitute the CreateProxy factory or assume a single exchange.\n\n## Browser API access\n\nDirect browser calls require CORS approval for the calling origin, methods and headers.\nContact PRED to confirm origin access. A CORS error is distinct from an authentication\nerror. Authenticated calls require freshly computed signatures and timestamps; entering\nstatic headers into an API explorer does not generate them.\n\n## Deposits — USDC on Base only\n\n**Only native USDC on Base (chain ID `8453`) is supported for deposits.**\nThe supported token contract is `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`,\nas listed in [Circle's USDC contract reference](https://developers.circle.com/stablecoins/usdc-contract-addresses).\nUSDC on other networks, bridged USDbC, USDT, ETH, and other tokens are not supported\ndeposit assets. Unsupported transfers will not fund the user's PRED trading balance;\nrecovery is not guaranteed.\n\nThe **deposit address is the user's own Safe proxy wallet**, not the signing EOA,\npartner wallet, or USDC token contract. For CLOB, retrieve it from the top-level\n`proxy_wallet_address` returned by `GET /clob/api/v1/user/account-status` using that\nuser's L2 credentials. For ordinary JWT login, use `data.proxy_wallet_addr`.\nAn empty address means Safe creation has not completed; do not send funds.\n\nDeposit by transferring the supported USDC token on Base to that Safe. There is no\nCLOB deposit-submission API; an account-status or balance request does not transfer funds.\nSee **Builder / Aggregator CLOB → Deposits** for address retrieval, the transfer\ncontract, and confirmation through `GET /clob/api/v1/portfolio/balance`.\n"}],"servers":[{"url":"https://www.pred.app","description":"PRED API on Base (chain ID 8453)."}],"paths":{"/":{"get":{"tags":["Overview"],"summary":"Overview — About PRED, getting started","description":"See the **Overview** tag description for: About PRED, getting started, X-API-Key, testing APIs, and environment configuration.\n","operationId":"overview","responses":{"200":{"description":"Documentation only"}}}}}}
```