# Fig Markets API Quickstart Guide

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:


```bash
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:**


```json
{
  "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:


```bash
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:**


```json
{
  "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:


```javascript
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**


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

**Option B: Using Credentials**


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

**Authentication Response:**


```json
{
  "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:**


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

**Heartbeat Response:**


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

#### Complete WebSocket Example

Here's a complete JavaScript example:


```javascript
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.