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

# API Integration

PolyMarks integrates with multiple external APIs.

## Polymarket Gamma API (Markets)

**Endpoint:** `https://gamma-api.polymarket.com/markets`

**Used For:** Fetching market data (questions, odds, volume, liquidity)

**Parameters:**

* `limit` - Number of markets to fetch (default: 100, max: 500)
* `closed` - Filter closed markets (default: false)
* `active` - Filter active markets (default: true)

**Sample Request:**

```bash
GET https://gamma-api.polymarket.com/markets?limit=100&closed=false&active=true
```

**Response Format:**

```json
{
  "data": [
    {
      "id": "...",
      "question": "Will Trump win 2024?",
      "description": "...",
      "outcomes": ["Yes", "No"],
      "volume": 1234567.89,
      "liquidity": 98765.43,
      "end_date": "2024-11-05T00:00:00Z",
      "slug": "trump-wins-2024",
      ...
    }
  ]
}
```

**Our Proxy:** `/api/markets`

## Polymarket Data API (Trades)

**Endpoint:** `https://data-api.polymarket.com/trades`

**Used For:** Fetching whale trades

**Parameters:**

* `limit` - Number of trades (default: 50, max: 200)
* `offset` - Pagination offset
* `filterType` - Filter by type (CASH)
* `filterAmount` - Minimum trade size (USD)
* `eventId` - Filter by market slug

**Sample Request:**

```bash
GET https://data-api.polymarket.com/trades?limit=50&filterType=CASH&filterAmount=1000
```

**Response Format:**

```json
[
  {
    "proxyWallet": "0x1ff26...",
    "name": "WhaleKing",
    "side": "BUY",
    "size": 10000,
    "price": 0.65,
    "totalValue": 6500,
    "title": "Trump wins 2024?",
    "slug": "trump-wins-2024",
    "eventSlug": "trump-wins-2024",
    "transactionHash": "0xabc123...",
    "timestamp": 1699564800,
    ...
  }
]
```

**Our Proxy:** `/api/trades`

## Helius RPC (Solana)

**Endpoint:** `https://mainnet.helius-rpc.com/?api-key=YOUR_KEY`

**Used For:** Future Solana wallet tracking features

**Sample Request:**

```bash
POST https://mainnet.helius-rpc.com/?api-key=YOUR_KEY
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getBalance",
  "params": ["wallet_address"]
}
```

**Currently:** Not actively used, prepared for future features

## CORS & Proxying

All external API calls go through Next.js API routes to avoid CORS:

**Before (CORS Error):**

```typescript
// ❌ Browser → External API (blocked by CORS)
fetch('https://gamma-api.polymarket.com/markets')
```

**After (Proxy):**

```typescript
// ✅ Browser → Next.js API Route → External API
fetch('/api/markets')
```

## Rate Limiting

**Polymarket APIs:**

* No official rate limit published
* We observed 429 errors when fetching whale data for 100+ markets simultaneously
* **Solution:** Disabled parallel market-whale fetching, only fetch on detail pages

**Best Practices:**

* Cache responses (60s for markets, 30s for trades)
* Batch requests when possible
* Use pagination (limit + offset)

## Error Handling

```typescript
try {
  const response = await fetch('/api/markets?limit=100')
  if (!response.ok) {
    throw new Error(`API error: ${response.status}`)
  }
  const data = await response.json()
  return transformMarkets(data)
} catch (error) {
  console.error('Error fetching markets:', error)
  return [] // Graceful fallback
}
```

Always return empty arrays/null instead of throwing to prevent UI crashes.


---

# 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://polymarks.gitbook.io/polymarks-docs/technical-documentation/api-integration.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.