Fig Markets API Quickstart Guide

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude

Welcome to the Fig API! This guide will help you get started with making your first API calls and establishing WebSocket connections.

Prerequisites

Before you begin, you'll need:

• Your API credentials (Client ID and Client Secret)
• Access to the Fig API endpoints
• A valid user account with appropriate permissions

1. REST API Authentication

Getting Started with REST API

To successfully make your first call to /v1/account/exchange-credentials, you need to authenticate using Bearer token authentication.

Step 1: Obtain an Access Token

First, you need to obtain an access token using your credentials. Make a POST request to the authentication endpoint:

curl -X POST https://api.test.figmarkets.com/v1/auth \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "your_client_id",
    "clientSecret": "your_client_secret"
  }'

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Step 2: Make Your First API Call

Now you can make authenticated requests to the API. Here's how to call the /v1/account/exchange-credentials endpoint:

curl -X GET https://api.test.figmarkets.com/v1/account/exchange-credentials \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Example Response:

{
  "success": true,
  "data": [
    {
      "credentialsId": 123,
      "exchangeId": 1,
      "alias": "My Exchange Account",
      "clientId": "exchange_client_id",
      "clientSecret": "exchange_client_secret"
    }
  ]
}

Important Notes:

• Always include the Authorization: Bearer YOUR_ACCESS_TOKEN header in your requests
• Access tokens expire after 1 hour (3600 seconds)
• You'll need the "trader" role to access account endpoints
• Store your access token securely and refresh it before expiration

2. WebSocket Connection

Getting Started with WebSocket

The WebSocket API allows you to receive real-time updates and subscribe to various channels. Here's how to connect and maintain a heartbeat.

Step 1: Establish WebSocket Connection

Connect to the WebSocket endpoint:

const ws = new WebSocket('wss://api.test.figmarkets.com/ws/v1');

Step 2: Authenticate Your Connection

Once connected, you must authenticate using JSON-RPC format. You can authenticate using either a token or credentials:

Option A: Using Access Token

{
  "id": 1,
  "method": "auth",
  "params": {
    "token": "your_access_token"
  }
}

Option B: Using Credentials

{
  "id": 1,
  "method": "auth",
  "params": {
    "clientId": "your_client_id",
    "clientSecret": "your_client_secret"
  }
}

Authentication Response:

{
  "id": 1,
  "method": "auth",
  "result": {
    "success": true,
    "token": "new_access_token_if_provided"
  }
}

Step 3: Send Heartbeat Messages

To maintain your connection, you must send heartbeat messages every 30 seconds. The server will close your connection if it doesn't receive a heartbeat within this timeframe.

Heartbeat Message Format:

{
  "id": 2,
  "method": "heartbeat",
  "params": {}
}

Heartbeat Response:

{
  "id": 2,
  "method": "heartbeat",
  "result": {
    "time": 1640995200000
  }
}

Complete WebSocket Example

Here's a complete JavaScript example:

const ws = new WebSocket('wss://api.test.figmarkets.com/ws/v1');

ws.onopen = function() {
    console.log('Connected to Fig WebSocket');

    // Authenticate
    ws.send(JSON.stringify({
        id: 1,
        method: "auth",
        params: {
            token: "your_access_token"
        }
    }));
};

ws.onmessage = function(event) {
    const message = JSON.parse(event.data);
    console.log('Received:', message);

    // Handle authentication response
    if (message.method === "auth" && message.result?.success) {
        console.log('Authentication successful');
        startHeartbeat();
    }

    // Handle heartbeat response
    if (message.method === "heartbeat") {
        console.log('Heartbeat acknowledged');
    }
};

function startHeartbeat() {
    // Send heartbeat every 25 seconds (before the 30-second timeout)
    setInterval(() => {
        ws.send(JSON.stringify({
            id: Date.now(),
            method: "heartbeat",
            params: {}
        }));
    }, 25000);
}

ws.onerror = function(error) {
    console.error('WebSocket error:', error);
};

ws.onclose = function() {
    console.log('WebSocket connection closed');
};

Important WebSocket Notes:

• Authentication Required: You must authenticate immediately after connecting
• Heartbeat Required: Send heartbeat messages every 25-30 seconds to maintain connection
• JSON-RPC Format: All messages must follow JSON-RPC 2.0 specification
• Rate Limiting: Most methods are rate-limited, except auth, auth/refresh, and heartbeat
• Reconnection: Implement reconnection logic for production applications
• Session Management: Your session expires with your access token

Error Handling

Common HTTP Status Codes

• 401 Unauthorized: Invalid or expired token
• 403 Forbidden: Insufficient permissions
• 429 Too Many Requests: Rate limit exceeded
• 500 Internal Server Error: Server error

WebSocket Error Codes

• -32700: Parse error (invalid JSON)
• -32601: Method not found
• -32603: Internal error
• -32700: Authentication error

Next Steps

Once you've successfully authenticated and made your first API call, you can:

1. Explore Account Management: Use the account endpoints to manage exchange credentials
2. Subscribe to Real-time Data: Use WebSocket subscriptions for live market data
3. Create RFQs: Start creating and managing RFQs (Request for Quotes)
4. Handle Trading: Execute trades and manage orders

For more detailed information, refer to the complete API documentation and endpoint reference.