> For the complete documentation index, see [llms.txt](https://docs.hello.trade/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hello.trade/developer-tools/rest-api/public-endpoints.md).

# Public Endpoints

Public endpoints do not require signatures or authentication.

**Base URL**: `https://api.app.hello.trade/api`

***

## GET /api/account\_summary

Get account balance, positions, and margin summary.

### Request

Query parameters:

| Parameter | Type    | Required | Description    |
| --------- | ------- | -------- | -------------- |
| `wallet`  | Address | Yes      | Wallet address |

**Example:**

```
GET /api/account_summary?wallet=0x742d35Cc6634C0532925a3b844Bc9e7595f12345
```

### Response

```json
{
  "assetPositions": [
    {
      "instrument": "NVDA",
      "marginMode": "Cross",
      "entryPx": "500.00",
      "leverage": 10,
      "liquidationPx": "450.00",
      "marginUsed": "100.00",
      "maxLeverage": 20,
      "positionValue": "1000.00",
      "returnOnEquity": "0.05",
      "szi": "2",
      "unrealizedPnl": "50.00"
    },
    {
      "instrument": "BTC",
      "marginMode": "Isolated",
      "entryPx": "65000.00",
      "leverage": 10,
      "liquidationPx": "59240.50",
      "marginUsed": "650.00",
      "maxLeverage": 40,
      "positionValue": "6500.00",
      "returnOnEquity": "0",
      "szi": "0.1",
      "unrealizedPnl": "0",
      "transferable": "0.00"
    }
  ],
  "crossMaintenanceMarginUsed": "25.00",
  "crossMarginSummary": {
    "accountValue": "10000.00",
    "totalMarginUsed": "100.00",
    "totalNtlPos": "1000.00",
    "totalRawUsd": "9950.00"
  },
  "maintenanceMarginUsed": "106.25",
  "marginSummary": {
    "accountValue": "10650.00",
    "totalMarginUsed": "750.00",
    "totalNtlPos": "7500.00",
    "totalRawUsd": "10600.00"
  },
  "time": 1705600000000,
  "withdrawable": "9900.00"
}
```

### Response Fields

**Top Level:**

| Field                        | Type   | Description                                |
| ---------------------------- | ------ | ------------------------------------------ |
| `assetPositions`             | Array  | Cross and isolated positions               |
| `crossMaintenanceMarginUsed` | string | Maintenance margin used (cross only)       |
| `crossMarginSummary`         | Object | Margin summary (cross only)                |
| `maintenanceMarginUsed`      | string | Maintenance margin used (cross + isolated) |
| `marginSummary`              | Object | Combined margin summary (cross + isolated) |
| `time`                       | i64    | Response timestamp (milliseconds)          |
| `withdrawable`               | string | Cross collateral available for withdrawal  |

**Asset Position:**

| Field            | Type   | Description                                                                      |
| ---------------- | ------ | -------------------------------------------------------------------------------- |
| `instrument`     | string | Instrument symbol                                                                |
| `marginMode`     | string | `Cross` or `Isolated`                                                            |
| `entryPx`        | string | Average entry price                                                              |
| `leverage`       | u32    | Position leverage (multiplier, e.g. 10 = 10×)                                    |
| `liquidationPx`  | string | Estimated liquidation price (omitted if not computable)                          |
| `marginUsed`     | string | Margin allocated to the position (for isolated: the position's dedicated margin) |
| `maxLeverage`    | u32    | Maximum allowed leverage (multiplier, e.g. 20 = 20×)                             |
| `positionValue`  | string | Notional position value                                                          |
| `returnOnEquity` | string | ROE percentage                                                                   |
| `szi`            | string | Position size (signed, positive = long)                                          |
| `unrealizedPnl`  | string | Unrealized PnL                                                                   |
| `transferable`   | string | Isolated collateral free to transfer to cross (isolated positions only)          |

**Margin Summary:**

| Field             | Type   | Description                                         |
| ----------------- | ------ | --------------------------------------------------- |
| `accountValue`    | string | Total account value                                 |
| `totalMarginUsed` | string | Total margin used                                   |
| `totalNtlPos`     | string | Total notional position value                       |
| `totalRawUsd`     | string | Total collateral balance (excluding unrealized PnL) |

***

## GET /api/open\_orders

Get the wallet's currently open (resting) orders. Like the other read endpoints, this is public — any wallet address may be queried (no ownership proof required).

### Request

Query parameters:

| Parameter     | Type    | Required | Description                                                                           |
| ------------- | ------- | -------- | ------------------------------------------------------------------------------------- |
| `wallet`      | Address | Yes      | Wallet address                                                                        |
| `mode`        | string  | No       | Margin scope: `combined` (default), `cross`, or `isolated`                            |
| `instruments` | string  | No       | Comma-separated symbols narrowing `mode=isolated` results (only valid with that mode) |

**Examples:**

```
GET /api/open_orders?wallet=0x742d35Cc6634C0532925a3b844Bc9e7595f12345
GET /api/open_orders?wallet=0x742d35Cc6634C0532925a3b844Bc9e7595f12345&mode=cross
GET /api/open_orders?wallet=0x742d35Cc6634C0532925a3b844Bc9e7595f12345&mode=isolated&instruments=BTC
```

### Response

```json
{
  "orders": [
    {
      "orderId": 123456789,
      "marginMode": "Cross",
      "traderOrderId": 1705600000001,
      "instrument": "NVDA",
      "orderType": "Limit",
      "side": "Buy",
      "quantity": "100",
      "price": "500.00",
      "timeInForce": "GTC",
      "status": "Active",
      "filledQuantity": "40",
      "filledPrice": "500.00",
      "remainingOpenQuantity": "60",
      "orderTimestamp": 1705600000000,
      "lastEventTimestamp": 1705600001000,
      "lastEventId": 987654321
    },
    {
      "orderId": 123456790,
      "marginMode": "Isolated",
      "traderOrderId": 1705600000002,
      "instrument": "BTC",
      "orderType": "Limit",
      "side": "Buy",
      "quantity": "0.05",
      "price": "64000.00",
      "timeInForce": "GTC",
      "status": "Active",
      "filledQuantity": "0",
      "filledPrice": "0",
      "remainingOpenQuantity": "0.05",
      "orderTimestamp": 1705600002000,
      "lastEventTimestamp": 1705600002000,
      "lastEventId": 987654322
    }
  ]
}
```

### Response Fields

**Top Level:**

| Field    | Type  | Description         |
| -------- | ----- | ------------------- |
| `orders` | Array | List of open orders |

**Order:**

| Field                   | Type   | Description                                                                                                                                                                                 |
| ----------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `orderId`               | u64    | Exchange order ID                                                                                                                                                                           |
| `marginMode`            | string | `Cross` or `Isolated`                                                                                                                                                                       |
| `traderOrderId`         | u64    | Client-supplied order ID (omitted for system-generated orders)                                                                                                                              |
| `instrument`            | string | Instrument symbol                                                                                                                                                                           |
| `orderType`             | string | `Limit`, `StopLimit`, `StopLoss`, `TakeProfit`; responses may also contain internal execution types (`LIT`) and retired types (`Market`, `Stop`, `MIT`, `MarketToLimit`) on historic orders |
| `side`                  | string | `Buy` or `Sell`                                                                                                                                                                             |
| `quantity`              | string | Order quantity                                                                                                                                                                              |
| `price`                 | string | Limit price (omitted if not applicable)                                                                                                                                                     |
| `stopPrice`             | string | Stop trigger price (omitted if not applicable)                                                                                                                                              |
| `timeInForce`           | string | `GTC`, `GTD`, `IOC`, `FOK`, `DAY`                                                                                                                                                           |
| `expiryDate`            | i64    | Expiry timestamp for `GTD` (milliseconds; omitted otherwise)                                                                                                                                |
| `status`                | string | `Active`, `Suspended`, `Executed`, `Cancelled`, `Pending`, `Ended`                                                                                                                          |
| `filledQuantity`        | string | Cumulative filled quantity                                                                                                                                                                  |
| `filledPrice`           | string | Weighted average filled price                                                                                                                                                               |
| `remainingOpenQuantity` | string | Quantity still open                                                                                                                                                                         |
| `orderTimestamp`        | i64    | Order creation timestamp (milliseconds)                                                                                                                                                     |
| `lastEventTimestamp`    | i64    | Timestamp of the last event on this order (milliseconds)                                                                                                                                    |
| `lastEventId`           | u64    | ID of the last event on this order                                                                                                                                                          |

***

## GET /api/historic/orders

Query historical orders.

### Request

Query parameters:

| Parameter       | Type     | Required | Description                                     |
| --------------- | -------- | -------- | ----------------------------------------------- |
| `wallet`        | Address  | Yes      | Wallet address                                  |
| `dateFrom`      | DateTime | No       | Start date (ISO 8601)                           |
| `dateTo`        | DateTime | No       | End date (ISO 8601)                             |
| `instruments`   | string   | No       | Comma-separated instruments (e.g., `NVDA,AAPL`) |
| `traderOrderId` | u64      | No       | Filter by client order ID                       |
| `orderId`       | u64      | No       | Filter by exchange order ID                     |
| `orderBy`       | string   | No       | Sort field                                      |
| `limit`         | u32      | No       | Max results (default: 50)                       |
| `offset`        | u64      | No       | Pagination offset                               |

**Example:**

```
GET /api/historic/orders?wallet=0x742d35Cc6634C0532925a3b844Bc9e7595f12345&instruments=NVDA&limit=50
```

### Response

```json
{
  "orders": [
    {
      "orderId": 123456789,
      "traderOrderId": 1705600000001,
      "instrumentId": 8,
      "instrument": "NVDA",
      "status": "Executed",
      "orderType": "Limit",
      "side": "Buy",
      "price": "500.00",
      "quantity": "100",
      "timeInForce": "GTC",
      "expiryDate": null,
      "createdAt": 1705600000,
      "filledPrice": "500.00",
      "filledQuantity": "100",
      "remainingOpenQuantity": "0",
      "lastEventTimestamp": 1705600001
    }
  ],
  "count": 1
}
```

### Response Fields

**Top Level:**

| Field    | Type  | Description                                      |
| -------- | ----- | ------------------------------------------------ |
| `orders` | Array | Order records                                    |
| `count`  | u64   | Total matching records (omitted if not computed) |

**Order:**

| Field                   | Type           | Description                                                                                                                                              |
| ----------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `orderId`               | u64            | Exchange order ID                                                                                                                                        |
| `traderOrderId`         | u64            | Client-supplied order ID (omitted for system-generated orders)                                                                                           |
| `instrumentId`          | u32            | Numeric instrument identifier                                                                                                                            |
| `instrument`            | string         | Instrument symbol                                                                                                                                        |
| `status`                | string         | `Active`, `Suspended`, `Executed`, `Cancelled`, `Pending`, `Ended`                                                                                       |
| `orderType`             | string         | `Limit`, `StopLimit`, `StopLoss`, `TakeProfit`; responses may also contain internal (`LIT`) and retired (`Market`, `Stop`, `MIT`, `MarketToLimit`) types |
| `side`                  | string         | `Buy` or `Sell`                                                                                                                                          |
| `price`                 | string \| null | Limit price (`null` if not applicable)                                                                                                                   |
| `quantity`              | string         | Order quantity                                                                                                                                           |
| `timeInForce`           | string         | `GTC`, `GTD`, `IOC`, `FOK`, `DAY`                                                                                                                        |
| `expiryDate`            | i64 \| null    | Expiry timestamp for `GTD`, in **Unix seconds** (`null` otherwise)                                                                                       |
| `createdAt`             | i64            | Order creation timestamp, in **Unix seconds**                                                                                                            |
| `filledPrice`           | string         | Weighted average filled price                                                                                                                            |
| `filledQuantity`        | string         | Cumulative filled quantity                                                                                                                               |
| `remainingOpenQuantity` | string         | Quantity still open                                                                                                                                      |
| `lastEventTimestamp`    | i64            | Timestamp of the last event on this order, in **Unix seconds**                                                                                           |
| `stopPrice`             | string         | Stop trigger price (omitted if not applicable)                                                                                                           |
| `minQuantity`           | string         | Minimum order quantity (omitted if not set)                                                                                                              |
| `cancelReason`          | string         | Reason for cancellation (omitted unless cancelled)                                                                                                       |

***

## GET /api/historic/trades

Query historical trades.

### Request

Query parameters:

| Parameter       | Type     | Required | Description                  |
| --------------- | -------- | -------- | ---------------------------- |
| `wallet`        | Address  | Yes      | Wallet address               |
| `dateFrom`      | DateTime | No       | Start date (ISO 8601)        |
| `dateTo`        | DateTime | No       | End date (ISO 8601)          |
| `instruments`   | string   | No       | Comma-separated instruments  |
| `tradeId`       | u64      | No       | Filter by trade ID           |
| `actionTypes`   | string   | No       | Comma-separated action types |
| `traderOrderId` | u64      | No       | Filter by client order ID    |
| `tradeDate`     | Date     | No       | Filter by trade date         |
| `orderId`       | u64      | No       | Filter by exchange order ID  |
| `orderBy`       | string   | No       | Sort field                   |
| `limit`         | u32      | No       | Max results (default: 50)    |
| `offset`        | u64      | No       | Pagination offset            |

**Example:**

```
GET /api/historic/trades?wallet=0x742d35Cc6634C0532925a3b844Bc9e7595f12345&limit=50
```

### Response

```json
{
  "trades": [
    {
      "timestamp": 1705600001,
      "actionType": "MatchedTrade",
      "orderId": 123456789,
      "traderOrderId": 1705600000001,
      "instrumentId": 8,
      "instrument": "NVDA",
      "side": "Buy",
      "price": "500.00",
      "quantity": "100",
      "tradeId": 987654321,
      "makerTaker": "Maker",
      "tradeDate": "2024-01-18"
    }
  ],
  "count": 1
}
```

| Field    | Type  | Description            |
| -------- | ----- | ---------------------- |
| `trades` | Array | Trade records          |
| `count`  | u64   | Total matching records |

***

## GET /api/historic/funding

Query a wallet's historic funding payments. Cross-margin and isolated-margin funding are merged into a single list, sorted newest-first, with each entry tagged by `marginMode`.

### Request

Query parameters:

| Parameter  | Type     | Required | Description                        |
| ---------- | -------- | -------- | ---------------------------------- |
| `wallet`   | Address  | Yes      | Wallet address                     |
| `market`   | u64      | No       | Filter by instrument ID            |
| `dateFrom` | DateTime | No       | Start time, inclusive (ISO 8601)   |
| `dateTo`   | DateTime | No       | End time, inclusive (ISO 8601)     |
| `limit`    | u32      | No       | Max results (default: 50, max: 50) |
| `offset`   | u64      | No       | Pagination offset                  |

For large histories, prefer narrowing with `dateFrom`/`dateTo` over large `offset` values.

**Example:**

```
GET /api/historic/funding?wallet=0x742d35Cc6634C0532925a3b844Bc9e7595f12345&market=8&limit=50
```

### Response

```json
{
  "funding": [
    {
      "market": 8,
      "timestamp": 1705600001,
      "delta": "1.50",
      "marginMode": "Cross"
    },
    {
      "market": 8,
      "timestamp": 1705513601,
      "delta": "-0.25",
      "marginMode": "Isolated"
    }
  ],
  "count": 2
}
```

| Field     | Type  | Description                   |
| --------- | ----- | ----------------------------- |
| `funding` | Array | Funding transactions          |
| `count`   | u64   | Records returned in this page |

**Funding Transaction:**

| Field        | Type   | Description                                                  |
| ------------ | ------ | ------------------------------------------------------------ |
| `market`     | u64    | Instrument ID                                                |
| `timestamp`  | i64    | Funding event time (Unix seconds)                            |
| `delta`      | string | Funding amount in USD (positive = received, negative = paid) |
| `marginMode` | string | `Cross` or `Isolated`                                        |

***

## GET /api/user/access-status/:walletAddress

Returns whether a wallet has been granted app access. Mirrors the predicate the authentication gate uses, so clients can branch on it before prompting the user to sign anything.

### Request

Path parameter:

| Parameter       | Type    | Required | Description                                           |
| --------------- | ------- | -------- | ----------------------------------------------------- |
| `walletAddress` | Address | Yes      | Wallet to query (case-insensitive; server lowercases) |

**Example:**

```
GET /api/user/access-status/0x742d35Cc6634C0532925a3b844Bc9e7595f12345
```

### Response

```json
{
  "hasAppAccess": true
}
```

| Field          | Type    | Description                                                                                                 |
| -------------- | ------- | ----------------------------------------------------------------------------------------------------------- |
| `hasAppAccess` | boolean | `true` iff the wallet has applied any referral code (affiliate or system) or was granted access by an admin |

If `false`, prompt the user for an invite code and submit it via `POST /api/referral/apply` (see [Authenticated Endpoints](/developer-tools/rest-api/authenticated-endpoints.md#post-apireferralapply)).

***

## Common Errors

| HTTP Status | Description                      |
| ----------- | -------------------------------- |
| 400         | Bad Request (invalid parameters) |
| 404         | Not Found (account not found)    |
| 500         | Internal Server Error            |

Error response format:

```json
{
  "error": "Error message"
}
```