Skip to content

REST API

The Synthetix REST API provides secure, authenticated access to trading operations and public market data through standard HTTP POST requests.

Overview

EndpointPathAuthenticationPurpose
Trade/v1/tradeEIP-712 signatureTrading operations, account management
Info/v1/infoNonePublic market data

All REST endpoints use POST method exclusively and accept/return JSON data.

For connection URLs, see Environments.

Authentication

Trade endpoints require EIP-712 signature authentication:

{
  "action": {
    "action": "methodName",
    // method-specific parameters
  },
  "nonce": 1704067200000,
  "signature": {
    "v": 28,
    "r": "0x...",
    "s": "0x..."
  }
}

See Authentication for detailed signing instructions.

Request Format

All requests must:

  1. Use POST method
  2. Include Content-Type: application/json header
  3. Send JSON body with required parameters

Example Request

curl -X POST https://papi.synthetix.io/v1/trade \
  -H "Content-Type: application/json" \
  -d '{
    "params": {
      "action": "placeOrders",
      "subAccountId": "1867542890123456789",
      "orders": [{
        "symbol": "BTC-USDT",
        "side": "buy",
        "orderType": "limitGtc",
        "price": "50000",
        "triggerPrice": "",
        "quantity": "0.1",
        "reduceOnly": false,
        "isTriggerMarket": false
      }]
    },
    "nonce": 1704067200000,
    "signature": {
      "v": 28,
      "r": "0x...",
      "s": "0x..."
    }
  }'

Response

All responses follow a consistent structure:

Success Response

{
  "status": "ok",
  "response": {
    // Method-specific response data
  },
  "request_id": "5ccf215d37e3ae6d",
  "timestamp": 1704067200000
}

Error Response

{
  "status": "error",
  "error": {
    "code": "ERROR_CODE",
    "message": "Error description",
    "details": { /* optional context */ }
  },
  "request_id": "5ccf215d37e3ae6d",
  "timestamp": 1704067200000
}

Rate Limits

REST API requests are rate-limited:

  • Trade endpoint: 300 requests per minute per IP
  • Info endpoint: 600 requests per minute per IP
  • See Rate Limits for details

Usage Examples

Batch Operations

{
  "action": {
    "action": "placeOrders",
    "orders": [
      { /* order 1 */ },
      { /* order 2 */ },
      { /* order 3 */ }
    ]
  }
}

Error Handling

const response = await fetch('https://papi.synthetix.io/v1/trade', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(request)
});
 
const data = await response.json();
 
if (data.status === 'error') {
  console.error('API Error:', data.error);
} else {
  console.log('Success:', data.response);
}

Retry Logic

async function requestWithRetry(endpoint, payload, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await makeRequest(endpoint, payload);
      return response;
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      const delay = Math.pow(2, i) * 1000;
      await sleep(delay);
    }
  }
}

WebSocket Alternative

For real-time data and lower latency trading, consider using the WebSocket API which offers:

  • Real-time market data streams
  • Lower latency for order placement
  • Reduced overhead for frequent operations

Next Steps