Dome API

https://docs.domeapi.io/
Admin
Dome API provides comprehensive access to real-time and historical prediction market data from...
Tokens:72,937
Snippets:442
Trust Score:3.4
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install the SDK

Source: https://docs.domeapi.io/websockets/polymarket-websockets-python-sdk

Install the package using pip.

```bash
pip install dome-api-sdk
```

--------------------------------

### Install the SDK

Source: https://docs.domeapi.io/websockets/polymarket-websockets-sdk

Use npm to install the package in your project.

```bash
npm install @dome-api/sdk
```

--------------------------------

### Install SDK Dependencies

Source: https://docs.domeapi.io/order-router/index

Install the core SDK and optional Privy authentication package.

```bash
npm install @dome-api/sdk
```

```bash
npm install @dome-api/sdk @privy-io/server-auth
```

--------------------------------

### Complete Subscription Example

Source: https://docs.domeapi.io/websockets/polymarket-websockets-python-sdk

A full example demonstrating client initialization, event handler registration, and subscription.

```python
from dome_api_sdk import DomeClient

dome = DomeClient({"api_key": "YOUR_API_KEY"})

# Define event handler
def handle_order(event):
    order = event.data
    print(f"New {order.side} order: {order.shares_normalized} shares @ {order.price}")
    print(f"Market: {order.market_slug}")
    print(f"User: {order.user}")

# Register event handler
dome.polymarket.websocket.on_event(handle_order)

# Subscribe to orders
try:
    subscription = dome.polymarket.websocket.subscribe({
        "platform": "polymarket",
        "version": 1,
        "type": "orders",
        "filters": {
            "users": [
                "0x6031b6eed1c97e853c6e0f03ad3ce3529351f96d",
                "0x7c3db723f1d4d8cb9c550095203b686cb11e5c6b"
            ]
        }
    })
    
    print(f"Subscribed with ID: {subscription.subscription_id}")
except Exception as error:
    print(f"Subscription failed: {error}")
```

--------------------------------

### Affiliate Platform Setup

Source: https://docs.domeapi.io/order-router/user-settings

One-time setup for platforms to ensure fee shares on all orders.

```bash
# One-time setup
curl -X POST https://api.domeapi.io/v1/polymarket/affiliate \
  -H "Authorization: Bearer YOUR_PLATFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"affiliateAddress": "0xYourPlatformWallet..."}'

# All subsequent orders automatically use your affiliate address
```

--------------------------------

### API Parameter Examples

Source: https://docs.domeapi.io/api-reference/endpoint/get-matching-markets-sports-sport

Examples of required parameters for the matching markets request.

```yaml
sport:
  type: string
  example: nfl
date:
  type: string
  example: '2025-08-16'
```

```yaml
'400':
  description: Bad Request - Missing or invalid parameters
  content:
    application/json:
      schema:
        type: object
        properties:
          error:
            type: string
            example: Missing required parameter
          message:
            type: string
            example: date parameter is required
```

--------------------------------

### Pagination Schema Example

Source: https://docs.domeapi.io/api-reference/endpoint/get-positions

Example values for pagination metadata fields.

```yaml
has_more:
  type: boolean
  description: Whether there are more results available
  example: false
limit:
  type: integer
  description: The limit used for this request
  example: 100
pagination_key:
  type: string
  nullable: true
  description: >-
    Pagination key to use for fetching next page, null if
    no more pages
  example: null
```

--------------------------------

### Get Market Price via cURL

Source: https://docs.domeapi.io/api-reference/endpoint/get-market-price

Examples for retrieving market prices using the cURL command-line tool.

```bash
curl
'https://api.domeapi.io/v1/polymarket/market-price/19701256321759583954581192053894521654935987478209343000964756587964612528044?at_time=1762164600'
```

```bash
curl
'https://api.domeapi.io/v1/polymarket/market-price/19701256321759583954581192053894521654935987478209343000964756587964612528044'
```

--------------------------------

### Pagination Key Example

Source: https://docs.domeapi.io/api-reference/endpoint/get-events

Example of the pagination_key string used to fetch subsequent pages of results.

```text
eyJsYXN0Vm9sdW1lIjoxNzEyMTMyNjYzLjk2MTYwNjMsImxhc3RFdmVudFNsdWciOiJuYmEtY2hhbXBpb24tMjAyNC0yMDI1In0=
```

--------------------------------

### Parameter Examples

Source: https://docs.domeapi.io/api-reference/endpoint/get-matching-markets-sports-sport?playground=open

Examples of the sport and date parameters used in the request.

```text
"nfl"
```

```text
"2025-08-16"
```

--------------------------------

### Install Dome API SDK

Source: https://docs.domeapi.io/

Install the required SDK package for your preferred programming language.

```bash
npm install @dome-api/sdk
```

```bash
pip install dome-api-sdk
```

--------------------------------

### Get Matching Markets Request Examples

Source: https://docs.domeapi.io/api-reference/endpoint/get-matching-markets-sports-sport?playground=open

Various language implementations to fetch matching markets for a specific sport.

```curl
curl --request GET \
  --url https://api.domeapi.io/v1/matching-markets/sports/{sport}
```

```python
import requests

url = "https://api.domeapi.io/v1/matching-markets/sports/{sport}"

response = requests.get(url)

print(response.text)
```

```javascript
const options = {method: 'GET'};

fetch('https://api.domeapi.io/v1/matching-markets/sports/{sport}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
```

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.domeapi.io/v1/matching-markets/sports/{sport}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.domeapi.io/v1/matching-markets/sports/{sport}"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

```java
HttpResponse<String> response = Unirest.get("https://api.domeapi.io/v1/matching-markets/sports/{sport}")
  .asString();
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.domeapi.io/v1/matching-markets/sports/{sport}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
```

--------------------------------

### Market Timing and Status Examples

Source: https://docs.domeapi.io/api-reference/endpoint/get-positions

Example values for market timestamps and status fields.

```yaml
start_time:
  type: integer
  description: Market start timestamp (Unix seconds)
  example: 1640995200
end_time:
  type: integer
  description: Market end timestamp (Unix seconds)
  example: 1672531200
completed_time:
  type: integer
  nullable: true
  description: >-
    Market completion timestamp (Unix seconds),
    currently always null
  example: null
close_time:
  type: integer
  nullable: true
  description: >-
    Market close timestamp (Unix seconds) if market is
    closed, null if still open
  example: 1672531200
game_start_time:
  type: string
  nullable: true
  description: >-
    Game start time for sports markets, null for
    non-sports markets
  example: '2025-01-15T19:00:00Z'
market_status:
  type: string
  enum:
    - open
    - closed
  description: Whether the market is open or closed
  example: open
negativeRisk:
  type: boolean
  description: Whether this market has negative risk
  example: false
```

--------------------------------

### Success Response Example

Source: https://docs.domeapi.io/order-router/link-account

Example of a successful JSON response from the setAllowances method.

```json
{
  "jsonrpc": "2.0",
  "id": "req-4",
  "result": {
    "success": true,
    "safeAddress": "0xABCD...",
    "allowancesSet": ["CTF_EXCHANGE", "NEG_RISK_CTF_EXCHANGE", "NEG_RISK_ADAPTER"],
    "transactionId": "019c022e-a853-78de-aa52-f59fd469d3d7",
    "transactionHash": "0x423b0c5c691aa34c37f793ed874b719ceb03a74cd3a98e3b550ecb5d095d86c8"
  }
}
```

--------------------------------

### Get Kalshi Market Price via cURL

Source: https://docs.domeapi.io/api-reference/endpoint/get-kalshi-market-price

Examples for retrieving market prices using cURL, including both real-time and historical lookups.

```bash
curl
'https://api.domeapi.io/v1/kalshi/market-price/KXNFLGAME-25AUG16ARIDEN-ARI?at_time=1762164600'
  -H 'Authorization: Bearer YOUR_TOKEN'
```

```bash
curl 'https://api.domeapi.io/v1/kalshi/market-price/KXNFLGAME-25AUG16ARIDEN-ARI' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

--------------------------------

### Unsubscribe Workflow Example

Source: https://docs.domeapi.io/websockets/polymarket-websockets-python-sdk

Demonstrates storing subscription IDs and unsubscribing from them later.

```python
# Store subscription IDs
subscriptions = []

# Subscribe and store ID
sub1 = dome.polymarket.websocket.subscribe({
    "platform": "polymarket",
    "version": 1,
    "type": "orders",
    "filters": {
        "users": ["0x6031b6eed1c97e853c6e0f03ad3ce3529351f96d"]
    }
})
subscriptions.append(sub1.subscription_id)

# Later, unsubscribe
dome.polymarket.websocket.unsubscribe(subscriptions[0])
print(f"Unsubscribed from subscription: {subscriptions[0]}")
```

--------------------------------

### Wallet with Positions Response Example

Source: https://docs.domeapi.io/api-reference/endpoint/get-positions

Example response structure for a wallet containing active positions.

```json
wallet_address: '0x1234567890abcdef1234567890abcdef12345678'
positions:
```

--------------------------------

### Error Response Examples

Source: https://docs.domeapi.io/api-reference/endpoint/get-matching-markets-sports

JSON schema examples for 400 Bad Request and 404 Not Found error states.

```json
'400':
  description: Bad Request - Missing or invalid parameters
  content:
    application/json:
      schema:
        type: object
        properties:
          error:
            type: string
            example: Missing required parameter
          message:
            type: string
            example: >-
              At least one polymarket_market_slug or kalshi_event_ticker
              is required
```

```json
'404':
  description: Not Found - No matching markets found
  content:
    application/json:
      schema:
        type: object
        properties:
          error:
            type: string
            example: Not found
          message:
            type: string
            example: No matching markets found for the provided parameters
```

--------------------------------

### API Response Examples

Source: https://docs.domeapi.io/api-reference/endpoint/get-matching-markets-sports-sport?playground=open

Example JSON responses for successful requests and error states.

```json
{
  "markets": {
    "nfl-ari-den-2025-08-16": [
      {
        "platform": "KALSHI",
        "event_ticker": "KXNFLGAME-25AUG16ARIDEN",
        "market_tickers": [
          "KXNFLGAME-25AUG16ARIDEN-ARI",
          "KXNFLGAME-25AUG16ARIDEN-DEN"
        ]
      },
      {
        "platform": "POLYMARKET",
        "market_slug": "nfl-ari-den-2025-08-16",
        "token_ids": [
          "34541522652444763571858406546623861155130750437169507355470933750634189084033",
          "104612081187206848956763018128517335758189185749897027211060738913329108425255"
        ]
      }
    ]
  },
  "sport": "nfl",
  "date": "2025-08-16"
}
```

```json
{
  "error": "Missing required parameter",
  "message": "date parameter is required"
}
```

--------------------------------

### Successful Price Response Examples

Source: https://docs.domeapi.io/api-reference/endpoint/get-chainlink-crypto-prices

Examples of successful API responses for latest price, time range queries, and paginated results.

```json
{
  "prices": [
    {
      "symbol": "btc/usd",
      "value": 67500.5,
      "timestamp": 1766130500000
    }
  ],
  "total": 1
}
```

```json
{
  "prices": [
    {
      "symbol": "btc/usd",
      "value": 67450.25,
      "timestamp": 1766130000000
    },
    {
      "symbol": "btc/usd",
      "value": 67500.5,
      "timestamp": 1766130500000
    },
    {
      "symbol": "btc/usd",
      "value": 67525.75,
      "timestamp": 1766131000000
    }
  ],
  "total": 3
}
```

```json
{
  "prices": [
    {
      "symbol": "btc/usd",
      "value": 67500.5,
      "timestamp": 1766130000000
    }
  ],
  "pagination_key": "eyJpZCI6IkNIQUlOTElOSyNidGMvdXNkIiwidGltZXN0YW1wIjoxNzY2MTMxMDAwMDAwfQ==",
  "total": 100
}
```

--------------------------------

### Bad Request Error Example

Source: https://docs.domeapi.io/api-reference/endpoint/get-candlestick

Example of a 400 Bad Request response indicating missing parameters.

```json
{
  "error": "Missing required query parameters",
  "required": "start_time, end_time"
}
```

--------------------------------

### Error Response Examples

Source: https://docs.domeapi.io/api-reference/endpoint/get-chainlink-crypto-prices

Examples of error responses returned when parameters are missing, invalid, or when server-side issues occur.

```json
{
  "error": "Missing currency parameter",
  "message": "currency is required"
}
```

```json
{
  "error": "Invalid currency format for chainlink",
  "message": "Chainlink currency must be slash-separated (e.g., btc/usd)"
}
```

```json
{
  "error": "Invalid start_time parameter",
  "message": "start_time must be a valid Unix timestamp in milliseconds"
}
```

```json
{
  "error": "Invalid end_time parameter",
  "message": "end_time must be a valid Unix timestamp in milliseconds"
}
```

```json
{
  "error": "Invalid time range",
  "message": "start_time must be less than or equal to end_time"
}
```

```json
{
  "error": "Invalid limit parameter",
  "message": "limit must be a positive integer"
}
```

```json
{
  "error": "Invalid pagination key format",
  "message": "Invalid pagination key format"
}
```

--------------------------------

### List Escrow Orders Response

Source: https://docs.domeapi.io/order-router/fee-escrow

Example JSON response for a successful list request.

```json
{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "orders": [
      {
        "orderId": "0x...",
        "payer": "0x...",
        "signer": "0x...",
        "feeAmount": "12500",
        "affiliate": "0x...",
        "status": "pending",
        "polymarketOrderId": "abc123",
        "pullFeeTxHash": "0x...",
        "distributeTxHash": null,
        "refundTxHash": null,
        "createdAt": "2024-01-15T10:30:00.000Z",
        "updatedAt": "2024-01-15T10:30:00.000Z"
      }
    ],
    "total": 1,
    "limit": 50,
    "offset": 0
  }
}
```

--------------------------------

### Get Escrow Order Response

Source: https://docs.domeapi.io/order-router/fee-escrow

Example JSON response for a successful escrow order retrieval.

```json
{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "order": {
      "orderId": "0x...",
      "payer": "0x...",
      "signer": "0x...",
      "feeAmount": "12500",
      "affiliate": "0x...",
      "status": "pending",
      "polymarketOrderId": "abc123",
      "pullFeeTxHash": "0x...",
      "distributeTxHash": null,
      "refundTxHash": null,
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    }
  }
}
```

--------------------------------

### GET /markets

Source: https://docs.domeapi.io/api-reference/endpoint/get-markets

Retrieves a paginated list of markets. Supports filtering by start and end time.

```APIDOC
## GET /markets

### Description
Retrieves a list of markets. You can filter the results by providing start_time and end_time parameters.

### Method
GET

### Endpoint
/markets

### Parameters
#### Query Parameters
- **start_time** (integer) - Optional - Filter markets from this Unix timestamp in seconds (inclusive)
- **end_time** (integer) - Optional - Filter markets until this Unix timestamp in seconds (inclusive)

### Response
#### Success Response (200)
- **markets** (array) - List of market objects
  - **market_slug** (string) - Unique identifier for the market
  - **event_slug** (string) - The event slug this market belongs to, or null
  - **condition_id** (string) - Condition ID for the market
  - **title** (string) - Market title
  - **start_time** (integer) - Unix timestamp when the market starts
  - **end_time** (integer) - Unix timestamp when the market ends
  - **completed_time** (integer) - Unix timestamp when the market was completed
  - **close_time** (integer) - Unix timestamp when the market was closed
  - **game_start_time** (string) - Datetime string in UTC format for sports markets
  - **tags** (array) - List of tags associated with the market
  - **volume_1_week** (number) - Trading volume in USD for the past week
  - **volume_1_month** (number) - Trading volume in USD for the past month
  - **volume_1_year** (number) - Trading volume in USD for the past year
  - **volume_total** (number) - Total trading volume in USD
  - **resolution_source** (string) - URL to the data source used for market resolution
  - **image** (string) - URL to the market image
  - **description** (string) - Market description

#### Response Example
{
  "markets": [
    {
      "market_slug": "btc-updown-15m-1762516800",
      "event_slug": "presidential-election-winner-2028",
      "condition_id": "0x6876ac2b6174778c973c118aac287c49057c4d5360f896729209fe985a2c07fb",
      "title": "Bitcoin Up or Down - November 7, 7:00AM-7:15AM ET",
      "start_time": 1762506140,
      "end_time": 1762517700,
      "completed_time": null,
      "close_time": null,
      "game_start_time": "2025-08-16 20:00:00.000",
      "tags": ["Up or Down", "Crypto Prices"],
      "volume_1_week": 0,
      "volume_1_month": 0,
      "volume_1_year": 0,
      "volume_total": 93.148228,
      "resolution_source": "https://data.chain.link/streams/btc-usd",
      "image": "https://polymarket-upload.s3.us-east-2.amazonaws.com/BTC+fullsize.png"
    }
  ]
}
```

--------------------------------

### Complete Subscription Workflow

Source: https://docs.domeapi.io/websockets/polymarket-websockets-sdk

A full example demonstrating connection, subscription, and event handling in one flow.

```typescript
import { DomeWebSocket } from '@dome-api/sdk';

const ws = new DomeWebSocket('YOUR_API_KEY');

// Wait for connection
ws.on('open', async () => {
  console.log('Connected, subscribing to orders...');
  
  try {
    const subscription = await ws.subscribe({
      platform: 'polymarket',
      version: 1,
      type: 'orders',
      filters: {
        users: [
          '0x6031b6eed1c97e853c6e0f03ad3ce3529351f96d',
          '0x7c3db723f1d4d8cb9c550095203b686cb11e5c6b'
        ]
      }
    });
    
    console.log('Subscribed with ID:', subscription.subscription_id);
  } catch (error) {
    console.error('Subscription failed:', error);
  }
});

// Handle order events
ws.on('event', (event) => {
  const order = event.data;
  console.log(`New ${order.side} order: ${order.shares_normalized} shares @ ${order.price}`);
  console.log(`Market: ${order.market_slug}`);
  console.log(`User: ${order.user}`);
});
```

--------------------------------

### Get Wallet Error Responses

Source: https://docs.domeapi.io/api-reference/endpoint/get-wallet

Examples of error responses returned by the API when invalid parameters are provided or a wallet is not found.

```json
summary: Both parameters provided
value:
  error: BAD_REQUEST
  message: Only one of eoa, proxy, or handle can be provided
```

```json
invalid_address:
  summary: Invalid wallet address format
  value:
    error: BAD_REQUEST
    message: Invalid wallet address format
```

```json
type: object
properties:
  error:
    type: string
    example: NOT_FOUND
  message:
    type: string
    example: Wallet not found
```

--------------------------------

### Get Markets Error Responses

Source: https://docs.domeapi.io/api-reference/endpoint/get-markets

Examples of JSON error responses returned by the API when validation fails or internal errors occur.

```json
search_too_short:
  summary: Search query too short
  value:
    error: Invalid search parameter
    message: search must be at least 2 characters long
```

```json
search_with_other_params:
  summary: Search with other parameters
  value:
    error: Invalid query parameters
    message: >-
      search parameter cannot be used with other filter
      parameters
```

```json
invalid_limit:
  summary: Invalid limit
  value:
    error: Invalid limit parameter
    message: limit must be a number between 1 and 100
```

```json
'500':
  description: Internal Server Error
  content:
    application/json:
      schema:
        type: object
        properties:
          error:
            type: string
            example: Internal Server Error
          message:
            type: string
            example: Failed to fetch markets data
```

--------------------------------

### Initialize and Manage Polymarket WebSocket Connections

Source: https://docs.domeapi.io/websockets/polymarket-websockets-python-sdk

Demonstrates client initialization with auto-reconnect, subscription management, event handling, and graceful shutdown using signal handlers.

```python
import signal
import sys
from dome_api_sdk import DomeClient

# Initialize client with auto-reconnect
dome = DomeClient({
    "api_key": "YOUR_API_KEY",
    "websocket": {
        "auto_reconnect": True,
        "reconnect_interval": 5,
        "max_reconnect_attempts": 10
    }
})

# Track subscriptions
subscriptions = {}

# Connection handler
def on_connect():
    print("✅ Connected to Dome API WebSocket")
    
    # Subscribe to orders
    try:
        sub = dome.polymarket.websocket.subscribe({
            "platform": "polymarket",
            "version": 1,
            "type": "orders",
            "filters": {
                "users": [
                    "0x6031b6eed1c97e853c6e0f03ad3ce3529351f96d",
                    "0x7c3db723f1d4d8cb9c550095203b686cb11e5c6b"
                ]
            }
        })
        
        subscriptions[sub.subscription_id] = {
            "platform": "polymarket",
            "version": 1,
            "type": "orders",
            "filters": {
                "users": [
                    "0x6031b6eed1c97e853c6e0f03ad3ce3529351f96d",
                    "0x7c3db723f1d4d8cb9c550095203b686cb11e5c6b"
                ]
            }
        }
        
        print(f"📡 Subscribed: {sub.subscription_id}")
    except Exception as error:
        print(f"❌ Subscription failed: {error}")

def on_error(error):
    print(f"❌ WebSocket error: {error}")

def on_close():
    print("🔌 Disconnected from WebSocket")

def on_reconnect():
    print("🔄 Reconnected, restoring subscriptions...")
    
    # Restore all subscriptions
    for sub_id, config in subscriptions.items():
        try:
            sub = dome.polymarket.websocket.subscribe(config)
            print(f"📡 Restored subscription: {sub.subscription_id}")
        except Exception as error:
            print(f"❌ Failed to restore subscription: {error}")

# Register handlers
dome.polymarket.websocket.on_connect(on_connect)
dome.polymarket.websocket.on_error(on_error)
dome.polymarket.websocket.on_close(on_close)
dome.polymarket.websocket.on_reconnect(on_reconnect)

# Handle order events
def handle_order_event(event):
    order = event.data
    print("\n📦 New Order Event:")
    print(f"   Subscription: {event.subscription_id}")
    print(f"   User: {order.user}")
    print(f"   Side: {order.side}")
    print(f"   Shares: {order.shares_normalized}")
    print(f"   Price: {order.price}")
    print(f"   Market: {order.market_slug}")
    print(f"   Title: {order.title}")
    from datetime import datetime
    print(f"   Timestamp: {datetime.fromtimestamp(order.timestamp).isoformat()}")

dome.polymarket.websocket.on_event(handle_order_event)

# Graceful shutdown
def signal_handler(sig, frame):
    print("\n🛑 Shutting down...")
    
    # Unsubscribe from all
    for sub_id in list(subscriptions.keys()):
        try:
            dome.polymarket.websocket.unsubscribe(sub_id)
            print(f"✅ Unsubscribed: {sub_id}")
        except Exception as error:
            print(f"❌ Unsubscribe failed: {error}")
    
    # Disconnect
    dome.polymarket.websocket.disconnect()
    sys.exit(0)

signal.signal(signal.SIGINT, signal_handler)

# Keep the script running
try:
    import time
    while True:
        time.sleep(1)
except KeyboardInterrupt:
    signal_handler(None, None)
```

--------------------------------

### Import the SDK

Source: https://docs.domeapi.io/websockets/polymarket-websockets-python-sdk

Import the DomeClient class to begin using the SDK.

```python
from dome_api_sdk import DomeClient
```

--------------------------------

### Connect via wscat

Source: https://docs.domeapi.io/websockets/polymarket-websockets

Use the wscat command-line tool to establish a connection to the WebSocket server.

```bash
wscat -c wss://ws.domeapi.io/<YOUR_API_KEY>
```

--------------------------------

### PolymarketRouterWithEscrow

Source: https://docs.domeapi.io/order-router/fee-escrow

Initializes the router with specific escrow configuration settings.

```APIDOC
## PolymarketRouterWithEscrow(config)

### Description
Initializes the router with escrow settings.

### Parameters
- **config** (object) - Configuration object
  - **apiKey** (string) - API key
  - **chainId** (number) - Chain ID
  - **escrow** (object) - Escrow settings
    - **feeBps** (number) - Fee in basis points
    - **deadlineSeconds** (number) - Authorization validity
    - **affiliate** (string) - Affiliate address
```

--------------------------------

### Connect to the WebSocket

Source: https://docs.domeapi.io/websockets/polymarket-websockets-python-sdk

Initialize the client with your API key to establish a connection.

```python
dome = DomeClient({"api_key": "YOUR_API_KEY"})
```

--------------------------------

### Initialize PolymarketRouterWithEscrow

Source: https://docs.domeapi.io/order-router/fee-escrow

Configure the router with escrow settings to enable automatic fee handling for orders.

```typescript
import { PolymarketRouterWithEscrow } from '@dome-api/sdk';

const router = new PolymarketRouterWithEscrow({
  apiKey: process.env.DOME_API_KEY,
  chainId: 137,
  escrow: {
    feeBps: 25,  // 0.25% fee
  },
});

// Place orders - fee escrow is automatic
const order = await router.placeOrder(
  {
    userId: 'user-123',
    marketId: '104173...',
    side: 'buy',
    size: 100,
    price: 0.50,
    signer,
  },
  credentials
);

// Response includes escrow info
console.log(order.escrowOrderId);   // Unique escrow order ID
console.log(order.feePulled);       // true
console.log(order.feeAmount);       // "12500" (0.0125 USDC for $50 order)
console.log(order.pullFeeTxHash);   // "0x..." transaction hash
```

--------------------------------

### Winning Outcome Schema Example

Source: https://docs.domeapi.io/api-reference/endpoint/get-positions

Example values for the winning outcome object properties.

```yaml
id:
  type: string
  description: Token ID of the winning outcome
  example: >-
    19701256321759583954581192053894521654935987478209343000964756587964612528044
label:
  type: string
  description: Label of the winning outcome
  example: 'Yes'
```

--------------------------------

### Initialize EOA Wallet and Place Order

Source: https://docs.domeapi.io/order-router/index

Configure a Privy-managed embedded wallet and link it to the router for order execution.

```typescript
import { PolymarketRouter, createPrivySignerFromEnv } from '@dome-api/sdk';

const router = new PolymarketRouter({
  chainId: 137,
  apiKey: process.env.DOME_API_KEY,
});

const signer = createPrivySignerFromEnv(walletId, walletAddress);

const credentials = await router.linkUser({
  userId: 'user-123',
  signer,
  walletType: 'eoa',
});

const order = await router.placeOrder(
  {
    userId: 'user-123',
    marketId: '...',
    side: 'buy',
    size: 100,
    price: 0.50,
    signer,
  },
  credentials
);
```

--------------------------------

### Configure Escrow Settings with TypeScript

Source: https://docs.domeapi.io/order-router/fee-escrow

Initialize the router with specific escrow parameters including fee basis points and deadlines.

```typescript
const router = new PolymarketRouterWithEscrow({
  apiKey: process.env.DOME_API_KEY,
  chainId: 137,
  escrow: {
    feeBps: 25,           // Fee in basis points (25 = 0.25%)
    deadlineSeconds: 3600, // Authorization validity (default: 1 hour)
    affiliate: '0x...',    // Optional affiliate address for fee sharing
  },
});
```

--------------------------------

### Import the SDK

Source: https://docs.domeapi.io/websockets/polymarket-websockets-sdk

Import the DomeWebSocket class to begin using the client.

```typescript
import { DomeWebSocket } from '@dome-api/sdk';
```

--------------------------------

### Candlestick Response Example

Source: https://docs.domeapi.io/api-reference/endpoint/get-candlestick

Example of a successful response containing candlestick data and token metadata.

```json
[
  {
    "end_period_ts": 1727827200,
    "open_interest": 8456498,
    "price": {
      "open": 0,
      "high": 0,
      "low": 0,
      "close": 0,
      "open_dollars": "0.0049",
      "high_dollars": "0.0049",
      "low_dollars": "0.0048",
      "close_dollars": "0.0048",
      "mean": 0,
      "mean_dollars": "0.0049",
      "previous": 0,
      "previous_dollars": "0.0049"
    },
    "volume": 8456498,
    "yes_ask": {
      "open": 0.00489,
      "close": 0.0048200000000000005,
      "high": 0.00491,
      "low": 0.0048,
      "open_dollars": "0.0049",
      "close_dollars": "0.0048",
      "high_dollars": "0.0049",
      "low_dollars": "0.0048"
    },
    "yes_bid": {
      "open": 0.00489,
      "close": 0.004829999990880811,
      "high": 0.004910000000138527,
      "low": 0.0048,
      "open_dollars": "0.0049",
      "close_dollars": "0.0048",
      "high_dollars": "0.0049",
      "low_dollars": "0.0048"
    }
  },
  {
    "token_id": "21742633143463906290569050155826241533067272736897614950488156847949938836455",
    "side": "Yes"
  }
]
```

--------------------------------

### Retrieve Matching Markets via API

Source: https://docs.domeapi.io/api-reference/endpoint/get-matching-markets-sports-sport?playground=open

Examples of how to fetch matching markets using various programming languages and tools.

```curl
curl --request GET \
  --url https://api.domeapi.io/v1/matching-markets/sports/{sport}
```

```python
import requests  
  
url = "https://api.domeapi.io/v1/matching-markets/sports/{sport}"  
  
response = requests.get(url)  
  
print(response.text)
```

```javascript
const options = {method: 'GET'};  
  
fetch('https://api.domeapi.io/v1/matching-markets/sports/{sport}', options)  
  .then(res => res.json())  
  .then(res => console.log(res))  
  .catch(err => console.error(err));
```

```php
<?php  
  
$curl = curl_init();  
  
curl_setopt_array($curl, [  
  CURLOPT_URL => "https://api.domeapi.io/v1/matching-markets/sports/{sport}",  
  CURLOPT_RETURNTRANSFER => true,  
  CURLOPT_ENCODING => "",  
  CURLOPT_MAXREDIRS => 10,  
  CURLOPT_TIMEOUT => 30,  
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,  
  CURLOPT_CUSTOMREQUEST => "GET",  
]);  
  
$response = curl_exec($curl);  
$err = curl_error($curl);  
  
curl_close($curl);  
  
if ($err) {  
  echo "cURL Error #:" . $err;  
} else {  
  echo $response;  
}
```

```go
package main  
  
import (  
	"fmt"  
	"net/http"  
	"io"  
)  
  
func main() {  
  
	url := "https://api.domeapi.io/v1/matching-markets/sports/{sport}"  
  
	req, _ := http.NewRequest("GET", url, nil)  
  
	res, _ := http.DefaultClient.Do(req)  
  
	defer res.Body.Close()  
	body, _ := io.ReadAll(res.Body)  
  
	fmt.Println(string(body))  
  
}
```

```java
HttpResponse<String> response = Unirest.get("https://api.domeapi.io/v1/matching-markets/sports/{sport}")  
  .asString();
```

```ruby
require 'uri'
require 'net/http'
  
url = URI("https://api.domeapi.io/v1/matching-markets/sports/{sport}")
  
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
  
request = Net::HTTP::Get.new(url)
  
response = http.request(request)
puts response.read_body
```

--------------------------------

### 500 Internal Server Error Example

Source: https://docs.domeapi.io/api-reference/endpoint/get-activity

Example of the error response returned when the server fails to process the request.

```json
{
  "error": "Internal Server Error",
  "message": "Failed to fetch activity data"
}
```

--------------------------------

### Prepare Session for Linking

Source: https://docs.domeapi.io/order-router/link-account

Request the EIP-712 payload required for user signing using the link-prepare endpoint.

```bash
curl -X POST https://api.domeapi.io/v1/polymarket/link-prepare \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "linkPrepare",
    "id": "req-1",
    "params": {
      "walletAddress": "0x1234567890123456789012345678901234567890",
      "walletType": "eoa"
    }
  }'
```

```typescript
const response = await fetch('https://api.domeapi.io/v1/polymarket/link-prepare', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    jsonrpc: '2.0',
    method: 'linkPrepare',
    id: 'req-1',
    params: {
      walletAddress: '0x1234567890123456789012345678901234567890',
      walletType: 'eoa',
    },
  }),
});

const data = await response.json();
const { sessionId, eip712Payload } = data.result;
```

```python
import requests

response = requests.post(
    'https://api.domeapi.io/v1/polymarket/link-prepare',
    json={
        'jsonrpc': '2.0',
        'method': 'linkPrepare',
        'id': 'req-1',
        'params': {
            'walletAddress': '0x1234567890123456789012345678901234567890',
            'walletType': 'eoa',
        },
    },
)

data = response.json()
session_id = data['result']['sessionId']
eip712_payload = data['result']['eip712Payload']
```

--------------------------------

### 400 Bad Request Error Examples

Source: https://docs.domeapi.io/api-reference/endpoint/get-activity

Examples of error responses returned when request parameters fail validation.

```json
{
  "error": "Invalid start_time parameter",
  "message": "start_time must be a valid Unix timestamp"
}
```

```json
{
  "error": "Invalid end_time parameter",
  "message": "end_time must be a valid Unix timestamp"
}
```

```json
{
  "error": "Invalid time range",
  "message": "start_time must be less than end_time"
}
```

```json
{
  "error": "Invalid limit parameter",
  "message": "limit must be a number between 1 and 1000"
}
```

```json
{
  "error": "Invalid pagination key",
  "message": "pagination_key is invalid or corrupted"
}
```

```json
{
  "error": "Invalid filter combination",
  "message": "Only one of market_slug or condition_id can be provided"
}
```

--------------------------------

### Link Safe Wallet with Privy Integration

Source: https://docs.domeapi.io/order-router/link-account

This example demonstrates the full flow for linking a Safe wallet, handling both new deployments and existing wallets, and setting up necessary allowances.

```typescript
// 1. Prepare - get EIP-712 payloads
const prepareResponse = await fetch('https://api.domeapi.io/v1/polymarket/link-prepare', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    jsonrpc: '2.0',
    method: 'linkPrepare',
    id: crypto.randomUUID(),
    params: {
      walletAddress: userWalletAddress,
      walletType: 'safe',
      autoDeploySafe: true,
    },
  }),
});

const prepareData = await prepareResponse.json();

if (prepareData.error) {
  throw new Error(`Prepare failed: ${prepareData.error.message}`);
}

const { sessionId, eip712Payload, safeDeployPayload, safeInfo } = prepareData.result;

// 2. Sign credentials payload using Privy
const signature = await privy.signTypedData({
  walletId,
  typedData: eip712Payload,
});

// 3. If Safe needs deployment, sign the deployment payload
let deploymentSignature;
if (safeDeployPayload) {
  deploymentSignature = await privy.signTypedData({
    walletId,
    typedData: safeDeployPayload,
  });
}

// 4. Complete - exchange signatures for credentials (and deploy Safe if needed)
const completeResponse = await fetch('https://api.domeapi.io/v1/polymarket/link-complete', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    jsonrpc: '2.0',
    method: 'linkComplete',
    id: crypto.randomUUID(),
    params: {
      sessionId,
      signature,
      ...(deploymentSignature && { deploymentSignature }),
    },
  }),
});

const completeData = await completeResponse.json();

if (completeData.error) {
  throw new Error(`Complete failed: ${completeData.error.message}`);
}

const { credentials, signerAddress, safeAddress, safeDeployed, safeDeployTxHash } = completeData.result;

// 5. Store credentials for future order placement
await database.savePolymarketCredentials(userId, {
  apiKey: credentials.apiKey,
  apiSecret: credentials.apiSecret,
  apiPassphrase: credentials.apiPassphrase,
  signerAddress,
  safeAddress,
});

if (safeDeployed) {
  console.log(`Safe deployed! Transaction: ${safeDeployTxHash}`);
}

// 6. Set allowances if needed
// For freshly deployed Safes, safeTxPayload is included in link-complete response (streamlined flow)
// For existing Safes, call /link-set-allowances-prepare first (standard flow)
const { safeTxPayload: allowancesPayload, allowancesToSet } = completeData.result;

if (allowancesPayload && allowancesToSet?.length > 0) {
  // Streamlined flow: safeTxPayload already included in link-complete response
  // Sign the messageHash using signMessage (eth_sign)
  const allowanceSignature = await privy.signMessage({
    walletId,
    message: allowancesPayload.messageHash,
  });

  // Submit - execute the allowance transactions
  const allowanceResponse = await fetch('https://api.domeapi.io/v1/polymarket/link-set-allowances', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      jsonrpc: '2.0',
      method: 'setAllowances',
      id: crypto.randomUUID(),
      params: { sessionId, chainId: 137, allowanceSignature },
    }),
  });

  const allowanceData = await allowanceResponse.json();
  console.log('Allowances set:', allowanceData.result.allowancesSet);
  console.log('Transaction hash:', allowanceData.result.transactionHash);
} else if (safeInfo && !safeInfo.hasAllowances) {
  // Standard flow for existing Safes: call /link-set-allowances-prepare first
  const prepareAllowanceResponse = await fetch('https://api.domeapi.io/v1/polymarket/link-set-allowances-prepare', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      jsonrpc: '2.0',
      method: 'setAllowancesPrepare',
      id: crypto.randomUUID(),
      params: { sessionId, chainId: 137 },
    }),
  });

  const prepareAllowanceData = await prepareAllowanceResponse.json();
  const { safeTxPayload, allowancesToSet: toSet } = prepareAllowanceData.result;

  if (toSet.length > 0) {
    const allowanceSignature = await privy.signMessage({
      walletId,
      message: safeTxPayload.messageHash,
    });

    const allowanceResponse = await fetch('https://api.domeapi.io/v1/polymarket/link-set-allowances', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        jsonrpc: '2.0',
        method: 'setAllowances',
        id: crypto.randomUUID(),
        params: { sessionId, chainId: 137, allowanceSignature },
      }),
    });

    const allowanceData = await allowanceResponse.json();
    console.log('Allowances set:', allowanceData.result.allowancesSet);
    console.log('Transaction hash:', allowanceData.result.transactionHash);
  }
}

console.log('Safe wallet linked successfully!');
```

--------------------------------

### Complete Account Linking Flow in TypeScript

Source: https://docs.domeapi.io/order-router/link-account

This example demonstrates the full sequence of preparing a link request, signing the EIP-712 payload, and completing the account linkage to store credentials.

```typescript
// 1. Prepare - get EIP-712 payload
const prepareResponse = await fetch('https://api.domeapi.io/v1/polymarket/link-prepare', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    jsonrpc: '2.0',
    method: 'linkPrepare',
    id: crypto.randomUUID(),
    params: {
      walletAddress: userWalletAddress,
      walletType: 'eoa',
    },
  }),
});

const prepareData = await prepareResponse.json();

if (prepareData.error) {
  throw new Error(`Prepare failed: ${prepareData.error.message}`);
}

const { sessionId, eip712Payload } = prepareData.result;

// 2. Sign - user signs in their wallet (TEE, mobile, etc.)
const signature = await signEip712InTEE(eip712Payload);

// 3. Complete - exchange signature for credentials
const completeResponse = await fetch('https://api.domeapi.io/v1/polymarket/link-complete', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    jsonrpc: '2.0',
    method: 'linkComplete',
    id: crypto.randomUUID(),
    params: {
      sessionId,
      signature,
    },
  }),
});

const completeData = await completeResponse.json();

if (completeData.error) {
  throw new Error(`Complete failed: ${completeData.error.message}`);
}

const { credentials, signerAddress } = completeData.result;

// 4. Store credentials for future order placement
await database.savePolymarketCredentials(userId, {
  apiKey: credentials.apiKey,
  apiSecret: credentials.apiSecret,
  apiPassphrase: credentials.apiPassphrase,
  signerAddress,
});

console.log('Account linked successfully!');
```
Tokens:
Raw