> ## Documentation Index
> Fetch the complete documentation index at: https://docs.limora.finance/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Technical documentation for the Limora API

This documentation covers the Limora API for developers building integrations, bots, or custom interfaces.

<Note>
  The API is currently in beta. Endpoints and response formats may change. Join
  our Discord for updates.
</Note>

***

## Overview

The Limora API provides programmatic access to:

* Market data and prices
* Trade execution
* Position management
* Account information
* Historical data

### Base URL

```
https://api.limora.finance/v1
```

### Authentication

Public endpoints (market data) require no authentication.

Private endpoints (trading, account) require wallet signature authentication.

***

## Authentication

### Wallet Signature Auth

For private endpoints, authenticate using wallet signatures:

<Steps>
  <Step title="Request Challenge">
    ```bash theme={null}
    GET /auth/challenge?address=0x...
    ```

    Response:

    ```json theme={null}
    {
      "challenge": "Sign this message to authenticate with Limora: nonce_abc123",
      "expiresAt": "2024-12-05T12:00:00Z"
    }
    ```
  </Step>

  <Step title="Sign Message">
    Sign the challenge message with your wallet.
  </Step>

  <Step title="Submit Signature">
    ```bash theme={null}
    POST /auth/verify
    Content-Type: application/json

    {
      "address": "0x...",
      "signature": "0x...",
      "challenge": "Sign this message..."
    }
    ```

    Response:

    ```json theme={null}
    {
      "token": "eyJhbGciOiJIUzI1NiIs...",
      "expiresAt": "2024-12-05T13:00:00Z"
    }
    ```
  </Step>

  <Step title="Use Token">
    Include the token in subsequent requests:

    ```
    Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
    ```
  </Step>
</Steps>

***

## Market Data

### Get Prices

Get current oracle prices for all supported assets.

```bash theme={null}
GET /prices
```

**Response:**

```json theme={null}
{
  "prices": [
    {
      "pair": "BTC/USDC",
      "price": 50000.0,
      "timestamp": "2024-12-05T10:30:00Z",
      "change24h": 2.5
    },
    {
      "pair": "ETH/USDC",
      "price": 3000.0,
      "timestamp": "2024-12-05T10:30:00Z",
      "change24h": 1.8
    }
  ]
}
```

### Get Single Price

```bash theme={null}
GET /prices/:pair
```

**Example:**

```bash theme={null}
GET /prices/BTC-USDC
```

**Response:**

```json theme={null}
{
  "pair": "BTC/USDC",
  "price": 50000.0,
  "timestamp": "2024-12-05T10:30:00Z",
  "high24h": 51000.0,
  "low24h": 49000.0,
  "change24h": 2.5,
  "volume24h": 15000000
}
```

### Get Price History

```bash theme={null}
GET /prices/:pair/history?interval=1h&limit=24
```

**Parameters:**

| Param    | Type      | Description                              |
| -------- | --------- | ---------------------------------------- |
| interval | string    | Candle interval: 1m, 5m, 15m, 1h, 4h, 1d |
| limit    | number    | Number of candles (max 1000)             |
| from     | timestamp | Start time (ISO 8601)                    |
| to       | timestamp | End time (ISO 8601)                      |

**Response:**

```json theme={null}
{
  "pair": "BTC/USDC",
  "interval": "1h",
  "candles": [
    {
      "timestamp": "2024-12-05T09:00:00Z",
      "open": 49800,
      "high": 50200,
      "low": 49700,
      "close": 50000
    }
  ]
}
```

***

## Trading

### Get Trading Pairs

```bash theme={null}
GET /pairs
```

**Response:**

```json theme={null}
{
  "pairs": [
    {
      "symbol": "BTC-USDC",
      "baseAsset": "BTC",
      "quoteAsset": "USDC",
      "maxLeverage": 50,
      "minCollateral": 10,
      "openingFee": 0.001,
      "closingFee": 0.001,
      "hourlyInterestRate": 0.00001
    }
  ]
}
```

### Open Position

```bash theme={null}
POST /trades
Authorization: Bearer <token>
Content-Type: application/json

{
  "pair": "BTC-USDC",
  "direction": "long",
  "collateral": 100,
  "leverage": 10,
  "stopLoss": 48000,
  "takeProfit": 55000
}
```

**Response:**

```json theme={null}
{
  "tradeId": "0x1234...abcd",
  "status": "pending",
  "pair": "BTC-USDC",
  "direction": "long",
  "collateral": 100,
  "leverage": 10,
  "size": 1000,
  "stopLoss": 48000,
  "takeProfit": 55000,
  "createdAt": "2024-12-05T10:30:00Z"
}
```

### Close Position

```bash theme={null}
POST /trades/:tradeId/close
Authorization: Bearer <token>
```

**Response:**

```json theme={null}
{
  "tradeId": "0x1234...abcd",
  "status": "closing",
  "exitPrice": 52500,
  "pnl": 50,
  "fees": 1.6,
  "netPnl": 48.4
}
```

### Cancel Pending Trade

```bash theme={null}
POST /trades/:tradeId/cancel
Authorization: Bearer <token>
```

**Response:**

```json theme={null}
{
  "tradeId": "0x1234...abcd",
  "status": "cancelled",
  "refundedCollateral": 100
}
```

***

## Positions

### Get Open Positions

```bash theme={null}
GET /positions
Authorization: Bearer <token>
```

**Response:**

```json theme={null}
{
  "positions": [
    {
      "tradeId": "0x1234...abcd",
      "pair": "BTC-USDC",
      "direction": "long",
      "size": 1000,
      "leverage": 10,
      "collateral": 100,
      "entryPrice": 50000,
      "currentPrice": 52000,
      "liquidationPrice": 45500,
      "unrealizedPnl": 40,
      "unrealizedPnlPercent": 40,
      "stopLoss": 48000,
      "takeProfit": 55000,
      "openedAt": "2024-12-05T08:00:00Z"
    }
  ]
}
```

### Get Position by ID

```bash theme={null}
GET /positions/:tradeId
Authorization: Bearer <token>
```

### Update Stop-Loss / Take-Profit

```bash theme={null}
PATCH /positions/:tradeId
Authorization: Bearer <token>
Content-Type: application/json

{
  "stopLoss": 49000,
  "takeProfit": 56000
}
```

***

## Account

### Get Balances

```bash theme={null}
GET /account/balances
Authorization: Bearer <token>
```

**Response:**

```json theme={null}
{
  "address": "0x...",
  "balances": {
    "wallet": {
      "USDC": 1000,
      "ETH": 0.5
    },
    "trading": {
      "USDC": 500,
      "available": 300,
      "inUse": 200
    },
    "matching": {
      "USDC": 2000,
      "available": 500,
      "matched": 1500
    }
  }
}
```

### Get Trade History

```bash theme={null}
GET /account/history
Authorization: Bearer <token>
```

**Parameters:**

| Param     | Type      | Description                |
| --------- | --------- | -------------------------- |
| pair      | string    | Filter by pair             |
| direction | string    | Filter: long, short        |
| status    | string    | Filter: closed, liquidated |
| from      | timestamp | Start date                 |
| to        | timestamp | End date                   |
| limit     | number    | Results per page (max 100) |
| offset    | number    | Pagination offset          |

**Response:**

```json theme={null}
{
  "trades": [
    {
      "tradeId": "0x1234...abcd",
      "pair": "BTC-USDC",
      "direction": "long",
      "size": 1000,
      "leverage": 10,
      "entryPrice": 50000,
      "exitPrice": 52500,
      "pnl": 50,
      "fees": 1.78,
      "netPnl": 48.22,
      "status": "closed",
      "openedAt": "2024-12-05T08:00:00Z",
      "closedAt": "2024-12-05T12:30:00Z"
    }
  ],
  "pagination": {
    "total": 150,
    "limit": 50,
    "offset": 0
  }
}
```

***

## WebSocket API

Real-time data is available via WebSocket connection.

### Connection

```javascript theme={null}
const ws = new WebSocket('wss://api.limora.finance/ws')
```

### Subscribe to Prices

```json theme={null}
{
  "type": "subscribe",
  "channel": "prices",
  "pairs": ["BTC-USDC", "ETH-USDC"]
}
```

**Updates:**

```json theme={null}
{
  "type": "price",
  "pair": "BTC-USDC",
  "price": 50100,
  "timestamp": "2024-12-05T10:30:01Z"
}
```

### Subscribe to Position Updates

Requires authentication first.

```json theme={null}
{
  "type": "auth",
  "token": "eyJhbGciOiJIUzI1NiIs..."
}

{
  "type": "subscribe",
  "channel": "positions"
}
```

**Updates:**

```json theme={null}
{
  "type": "position_update",
  "tradeId": "0x1234...abcd",
  "currentPrice": 50150,
  "unrealizedPnl": 15.0,
  "marginLevel": 125
}
```

***

## Rate Limits

| Endpoint Type | Limit               |
| ------------- | ------------------- |
| Public        | 100 requests/minute |
| Authenticated | 300 requests/minute |
| WebSocket     | 50 messages/minute  |

Rate limit headers:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1701778800
```

***

## Error Handling

### Error Response Format

```json theme={null}
{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Not enough USDC in trading balance",
    "details": {
      "required": 100,
      "available": 50
    }
  }
}
```

### Common Error Codes

| Code                   | Description                       |
| ---------------------- | --------------------------------- |
| `UNAUTHORIZED`         | Invalid or missing authentication |
| `INVALID_PARAM`        | Invalid parameter value           |
| `INSUFFICIENT_BALANCE` | Not enough funds                  |
| `POSITION_NOT_FOUND`   | Trade ID doesn't exist            |
| `RATE_LIMITED`         | Too many requests                 |
| `INTERNAL_ERROR`       | Server error                      |

***

## SDK

### JavaScript/TypeScript

```bash theme={null}
npm install @limora/sdk
```

```typescript theme={null}
import { Limora } from '@limora/sdk'

const limora = new Limora({
  network: 'base-mainnet',
  provider: window.ethereum,
})

// Get prices
const price = await limora.getPrice('BTC-USDC')

// Open position
const trade = await limora.openLong({
  pair: 'BTC-USDC',
  collateral: 100,
  leverage: 10,
  stopLoss: 48000,
  takeProfit: 55000,
})

// Subscribe to updates
limora.subscribe('prices', ['BTC-USDC'], update => {
  console.log(update)
})
```

### Python

```bash theme={null}
pip install limora-sdk
```

```python theme={null}
from limora import Limora

client = Limora(
    network='base-mainnet',
    private_key=os.environ['PRIVATE_KEY']
)

# Get prices
price = client.get_price('BTC-USDC')

# Open position
trade = client.open_long(
    pair='BTC-USDC',
    collateral=100,
    leverage=10
)
```

***

## Changelog

### v1.0.0 (Beta)

* Initial API release
* Market data endpoints
* Trading endpoints
* Account endpoints
* WebSocket support

***

<Card title="Support" icon="headset" href="/support">
  Need help? Contact our support team.
</Card>