Liquidity.io Docs

Full reference for the Liquidity.io exchange API. All endpoints are served by the ATS binary. Authentication, market data, orders, portfolio, and transactions.

Base URL: https://api.{env}.satschel.com/v1

Environment	Base URL
Production	`https://api.satschel.com/v1`
Staging	`https://api.stage.satschel.com/v1`
Development	`https://api.dev.satschel.com/v1`

Authentication

All authenticated endpoints require two headers:

Authorization: Bearer {iam_access_token}
tenant-authorization: {tenant_jwt}

Obtain IAM Token

POST https://iam.{env}.satschel.com/api/login/oauth/access_token
Content-Type: application/x-www-form-urlencoded

grant_type=password&client_id=liquidity-exchange-client-id&username={phone}&password={otp}&scope=openid+profile+email+phone

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 7200,
  "scope": "openid profile email phone",
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}

The access_token is a JWT containing the user's identity. The owner claim scopes all data queries to the user's organization. Tokens expire after 2 hours.

Obtain Tenant JWT

POST https://api.{env}.satschel.com/v1/auth/tenant-token
Authorization: Bearer {iam_access_token}

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Include this as the tenant-authorization header on all subsequent requests.

Assets

List Assets

GET /v1/assets?marketRail={rail}&category={category}&tradeable=true

Param	Type	Required	Description
`marketRail`	string	No	`public`, `private`, `digital`
`category`	string	No	`stocks`, `crypto`, `privates`, `pre-ipo`, `fixed-income`, `commodities`, `forex`
`tradeable`	boolean	No	Filter to tradeable assets only
`search`	string	No	Full-text search by symbol or name

Response:

{
  "data": [
    {
      "id": "AAPL",
      "symbol": "AAPL",
      "name": "Apple Inc. Common Stock",
      "type": "stocks",
      "exchange": "NASDAQ",
      "status": "APPROVED",
      "price": 249.93,
      "change": -4.30,
      "changesPercentage": -1.69,
      "image": "https://cdn.satschel.com/assets/AAPL.png"
    },
    {
      "id": "BTC",
      "symbol": "BTC",
      "name": "Bitcoin",
      "type": "crypto",
      "exchange": null,
      "status": "APPROVED",
      "price": 83421.50,
      "change": 1250.00,
      "changesPercentage": 1.52,
      "image": "https://cdn.satschel.com/assets/BTC.png"
    }
  ],
  "message": "ok"
}

Get Asset Detail

GET /v1/assets/{id}

Returns full asset detail including market data, metadata, accreditation requirements, and offering info.

Response:

{
  "data": {
    "id": "AAPL",
    "symbol": "AAPL",
    "name": "Apple Inc. Common Stock",
    "type": "stocks",
    "exchange": "NASDAQ",
    "change": -4.30,
    "changesPercentage": -1.69,
    "accreditationType": null,
    "offeringType": "Retail (Non Accredited)",
    "marketData": {
      "perDay": [
        {
          "timestamp": "2026-03-18T04:00:00Z",
          "open": 252.625,
          "high": 254.94,
          "low": 249,
          "close": 249.94,
          "volume": 36035199
        }
      ]
    }
  }
}

Get Real-Time Quote

GET /v1/assets/{id}/quote

Returns the latest quote for an asset. Frontend should poll every 5 seconds.

Response:

{
  "assetId": "AAPL",
  "last": 249.93,
  "open": 252.61,
  "high": 254.91,
  "low": 249.01,
  "prevClose": 254.23,
  "change": -4.30,
  "changePercent": -1.69,
  "volume": 979956,
  "timestamp": "2026-03-19T00:34:44Z"
}

Get Chart Data

GET /v1/assets/{id}/chart?range={range}&interval={interval}

Param	Values
`range`	`1d`, `5d`, `1m`, `3m`, `6m`, `1y`, `5y`
`interval`	`1m`, `5m`, `15m`, `1h`, `1d`

Response:

{
  "data": [
    {
      "time": 1773820800000,
      "open": 255.00,
      "high": 255.01,
      "low": 255.00,
      "close": 255.01,
      "volume": 1084
    }
  ]
}

Get Order Book

GET /v1/assets/{id}/book

Returns current bid/ask depth. Frontend should poll every 3 seconds.

Response:

{
  "assetId": "AAPL",
  "bids": [
    { "price": 239.87, "size": 100 },
    { "price": 239.50, "size": 250 }
  ],
  "asks": [
    { "price": 265.40, "size": 100 },
    { "price": 265.75, "size": 150 }
  ],
  "timestamp": "2026-03-19T00:34:45Z"
}

GET /v1/navigation

Returns the market rail and category structure for the exchange UI. Fetched once at boot.

{
  "rails": [
    {
      "id": "public",
      "label": "Public",
      "categories": [
        { "id": "stocks", "label": "Stocks" },
        { "id": "fixed-income", "label": "Fixed Income" },
        { "id": "commodities", "label": "Commodities" },
        { "id": "forex", "label": "Forex" }
      ]
    },
    {
      "id": "private",
      "label": "Private",
      "categories": [
        { "id": "privates", "label": "Privates" },
        { "id": "pre-ipo", "label": "Pre-IPO" }
      ]
    },
    {
      "id": "digital",
      "label": "Digital",
      "categories": [
        { "id": "crypto", "label": "Crypto" }
      ]
    }
  ]
}

Orders

Create Order

POST /v1/orders
Authorization: Bearer {iam_access_token}
tenant-authorization: {tenant_jwt}
Content-Type: application/json

Request:

{
  "assetId": "AAPL",
  "side": "BUY",
  "orderType": "market",
  "quantity": 10
}

Limit order:

{
  "assetId": "AAPL",
  "side": "BUY",
  "orderType": "limit",
  "quantity": 10,
  "limitPrice": 245.00
}

Pre-IPO order:

{
  "assetId": "SPACEX-PRE",
  "side": "BUY",
  "orderType": "market",
  "quantity": 5,
  "isPreIPO": true
}

Response:

{
  "data": {
    "orderId": "ord_a1b2c3d4e5f6",
    "assetId": "AAPL",
    "side": "BUY",
    "orderType": "market",
    "quantity": 10,
    "status": "PENDING",
    "createdAt": "2026-03-19T00:35:00Z"
  },
  "message": "ok"
}

Validation performed on creation:

Authentication (IAM token + tenant JWT)
Asset exists and is tradeable
Accreditation check against asset's accreditationType
RegCF investment limit check (if applicable)
Portfolio ownership verification (for SELL orders)
Resale restriction check (for restricted lots)

Get Order

GET /v1/orders/{id}
Authorization: Bearer {iam_access_token}
tenant-authorization: {tenant_jwt}

Response:

{
  "data": {
    "orderId": "ord_a1b2c3d4e5f6",
    "assetId": "AAPL",
    "side": "BUY",
    "orderType": "market",
    "quantity": 10,
    "filledQuantity": 10,
    "averagePrice": 249.93,
    "status": "EXECUTED",
    "createdAt": "2026-03-19T00:35:00Z",
    "executedAt": "2026-03-19T00:35:02Z"
  }
}

List Orders

GET /v1/orders?status={status}&assetId={assetId}
Authorization: Bearer {iam_access_token}
tenant-authorization: {tenant_jwt}

Param	Type	Description
`status`	string	`PENDING`, `EXECUTED`, `CANCELLED`, `ALL`
`assetId`	string	Filter by asset

Response:

{
  "data": [
    {
      "orderId": "ord_a1b2c3d4e5f6",
      "assetId": "AAPL",
      "side": "BUY",
      "orderType": "market",
      "quantity": 10,
      "status": "EXECUTED",
      "createdAt": "2026-03-19T00:35:00Z"
    }
  ],
  "message": "ok"
}

Cancel Order

DELETE /v1/orders/{id}
Authorization: Bearer {iam_access_token}
tenant-authorization: {tenant_jwt}

Response:

{
  "data": {
    "orderId": "ord_a1b2c3d4e5f6",
    "status": "CANCELLED",
    "cancelledAt": "2026-03-19T00:36:00Z"
  },
  "message": "ok"
}

Only PENDING orders can be cancelled.

Portfolio

Get Portfolio

GET /v1/portfolio
Authorization: Bearer {iam_access_token}
tenant-authorization: {tenant_jwt}

Returns the user's current holdings across all asset types.

{
  "data": [
    {
      "assetId": "AAPL",
      "symbol": "AAPL",
      "name": "Apple Inc. Common Stock",
      "type": "stocks",
      "quantity": 50,
      "averageCost": 245.00,
      "currentPrice": 249.93,
      "marketValue": 12496.50,
      "unrealizedPnl": 246.50,
      "unrealizedPnlPercent": 2.01
    },
    {
      "assetId": "BTC",
      "symbol": "BTC",
      "name": "Bitcoin",
      "type": "crypto",
      "quantity": 0.5,
      "averageCost": 78000.00,
      "currentPrice": 83421.50,
      "marketValue": 41710.75,
      "unrealizedPnl": 2710.75,
      "unrealizedPnlPercent": 6.95
    }
  ],
  "message": "ok"
}

Get Exchange Portfolio

GET /v1/exchange-portfolio
Authorization: Bearer {iam_access_token}
tenant-authorization: {tenant_jwt}

Returns portfolio with additional exchange-specific metadata (lot tracking, restriction dates, acquisition info).

{
  "data": [
    {
      "assetId": "SPACEX-PRE",
      "symbol": "SPACEX-PRE",
      "name": "SpaceX Series C",
      "type": "privates",
      "quantity": 5,
      "averageCost": 100.00,
      "lots": [
        {
          "quantity": 5,
          "acquisitionDate": "2025-09-15T00:00:00Z",
          "restrictionEndDate": "2026-09-15T00:00:00Z",
          "isRestricted": true,
          "offeringType": "506c"
        }
      ]
    }
  ]
}

Transactions

List Transactions

GET /v1/fortress-transactions?type={type}
Authorization: Bearer {iam_access_token}
tenant-authorization: {tenant_jwt}

Param	Type	Description
`type`	string	`deposit`, `withdrawal`, `trade`, `all`

Response:

{
  "data": [
    {
      "id": "txn_abc123",
      "type": "trade",
      "assetId": "BTC",
      "side": "BUY",
      "quantity": 0.1,
      "price": 83000.00,
      "total": 8300.00,
      "fee": 24.90,
      "status": "completed",
      "timestamp": "2026-03-18T14:30:00Z"
    }
  ],
  "message": "ok"
}

Account

Get Account Info

GET /v1/account
Authorization: Bearer {iam_access_token}
tenant-authorization: {tenant_jwt}

{
  "data": {
    "userId": "usr_xyz789",
    "email": "user@example.com",
    "phone": "+15551234567",
    "kycStatus": "completed",
    "accreditationStatus": "completed",
    "accreditationType": "506c",
    "cashBalance": 25000.00,
    "buyingPower": 25000.00
  }
}

Accreditation Enforcement

Per SEC Regulation D and the Liquidity.io Secondary Private Resale Disclosure:

Asset `accreditationType`	Buyer Requirement
`506c`	Verified accredited investor (Simplici third-party verification)
`506b`	Self-certified accredited investor
`Retail` / `null`	No accreditation gate

The backend enforces this on ALL order creation paths (standard, pre-IPO, order updates). Orders that fail accreditation checks are rejected with 400 Bad Request.

Rate Limiting

Endpoint Type	Limit
Public market data	100 requests/minute
Authenticated endpoints	300 requests/minute
Order placement	10 orders/second

Rate limit headers are included in all responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1710807360

Error Handling

All errors follow a standard format:

{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Insufficient balance for order",
    "details": {
      "required": 100.50,
      "available": 50.00
    }
  }
}

Error Codes

Code	HTTP Status	Description
`UNAUTHORIZED`	401	Missing or invalid authentication
`FORBIDDEN`	403	Insufficient permissions or accreditation
`ASSET_NOT_FOUND`	404	Asset does not exist
`ORDER_NOT_FOUND`	404	Order does not exist
`INVALID_ORDER_TYPE`	400	Unsupported order type for this asset
`INSUFFICIENT_BALANCE`	400	Not enough cash or asset balance
`ACCREDITATION_REQUIRED`	400	Asset requires accredited investor status
`RESALE_RESTRICTED`	400	Lot is within restriction hold period
`RATE_LIMIT_EXCEEDED`	429	Too many requests
`INTERNAL_ERROR`	500	Server error

Legacy Endpoints

These endpoints are served by ATS for backwards compatibility. Do not use in new code.

Legacy	Canonical Replacement
`/v1/exchange-explorers`	`/v1/assets?...`
`/v1/exchange-assets/{id}`	`/v1/assets/{id}`
`/v1/stock-summaries`	`/v1/assets?category=stocks`
`/v1/exchange-orderbook`	`/v1/assets/{id}/book`
`/v1/asset-chats`	`/v1/assets/{id}/chart`
`/v1/fortress-account-info`	`/v1/account`

API Reference

Authentication

Obtain IAM Token

Obtain Tenant JWT

Assets

List Assets

Get Asset Detail

Get Real-Time Quote

Get Chart Data

Get Order Book

Navigation

Orders

Create Order

Get Order

List Orders

Cancel Order

Portfolio

Get Portfolio

Get Exchange Portfolio

Transactions

List Transactions

Account

Get Account Info

Accreditation Enforcement

Rate Limiting

Error Handling

Error Codes

Legacy Endpoints

On this page