Developers

Build on tokenized markets.

A consistent REST API for assets, quotes, orders and portfolios, real-time streams, and signed webhooks. All endpoints in this environment serve simulated data.

Introduction

The API is organised around REST, returns JSON, and uses standard HTTP status codes. Every response that contains market data includes a meta.simulated flag — always check it.

Base URL

https://api.xstockss.fun/api/v1

Demo environment: prices are simulated and orders are paper trades. No real asset is bought or sold.

Authentication

Authenticate server-to-server requests with a secret API key in the Authorization header. Keys are scoped: read (market data, portfolio) and trade (orders). Browser sessions use httpOnly cookies plus a CSRF token and are not intended for programmatic use.

Request

curl https://api.xstockss.fun/api/v1/portfolio \
  -H "Authorization: Bearer sk_demo_••••••••••••"

Never embed secret keys in mobile apps or browser code. Rotate keys from the API keys panel below; revoked keys stop working immediately.

Market Data

Market data is served through a provider abstraction. In demo mode every value comes from a deterministic simulation model; with a licensed provider configured, the same endpoints serve provider data.

GET/api/v1/market-status

Current US equity session status and the next session change.

GET/api/v1/assets/{symbol}/bars?timeframe=1D

OHLCV bars. Timeframes: 1H, 1D, 1W, 1M, 3M, 1Y, 5Y.

Response

{
  "data": [
    {
      "time": 1791100800,
      "open": 182.41,
      "high": 182.66,
      "low": 182.3,
      "close": 182.52,
      "volume": 845213
    }
  ],
  "meta": {
    "symbol": "NVDA",
    "timeframe": "1D",
    "source": "demo",
    "simulated": true
  }
}

Assets

GET/api/v1/assets

List instruments. Filters: search, sector, network, country, tradable. Add include=quotes to embed quotes.

GET/api/v1/assets/NVDA

A single instrument with token configuration per network and its current quote.

Response

{
  "data": {
    "symbol": "NVDA",
    "name": "NVIDIA Corporation",
    "kind": "stock",
    "tokenSymbol": "sNVDA",
    "networks": [
      "ethereum",
      "solana",
      "base",
      "arbitrum"
    ],
    "tokenStatus": "tokenized",
    "tradable": true,
    "tokens": [
      {
        "network": "ethereum",
        "standard": "ERC-20 (permissioned extension)",
        "decimals": 18,
        "contractAddress": null,
        "status": "tokenized"
      }
    ]
  },
  "meta": {
    "source": "demo",
    "simulated": true
  }
}

Quotes

GET/api/v1/quotes?symbols=NVDA,AAPL

Quotes for up to 200 symbols.

GET/api/v1/quotes/NVDA

Latest quote. price is the token reference price; underlyingPrice freezes outside regular hours.

Response

{
  "data": {
    "symbol": "NVDA",
    "price": 185.01,
    "underlyingPrice": 183.59,
    "change24h": 4.1,
    "changePct24h": 0.0227,
    "changePct7d": 0.0312,
    "open24h": 180.91,
    "high24h": 185.79,
    "low24h": 180.91,
    "volume24h": 280108718,
    "bid": 184.88,
    "ask": 185.14,
    "marketStatus": "closed",
    "timestamp": 1791011541150,
    "source": "demo"
  },
  "meta": {
    "source": "demo",
    "simulated": true
  }
}

Orders

Orders are validated server-side (instrument, network, size limits, balance) and executed by the configured execution provider. Supply a clientOrderId to make submission idempotent.

POST/api/v1/ordersscope: trade

Submit a market, limit or stop order.

Request

curl -X POST https://api.xstockss.fun/api/v1/orders \
  -H "Authorization: Bearer sk_demo_••••" \
  -H "Content-Type: application/json" \
  -d '{"symbol":"NVDA","side":"BUY","type":"LIMIT","quantity":2.5,"limitPrice":180,"network":"ethereum","clientOrderId":"rebalance-2026-10-03-001"}'

201 Created

{
  "data": {
    "id": "ord_…",
    "symbol": "NVDA",
    "side": "BUY",
    "type": "LIMIT",
    "quantity": 2.5,
    "limitPrice": 180,
    "status": "OPEN",
    "filledQty": 0,
    "network": "ethereum",
    "provider": "demo",
    "simulated": true
  },
  "meta": {
    "simulated": true,
    "notice": "Simulated order — no real asset will be purchased."
  }
}

GET/api/v1/orders?status=OPENscope: read

List orders and recent trades.

DELETE/api/v1/orders/{id}scope: trade

Cancel an open order.

Portfolio

GET/api/v1/portfolioscope: read

Cash, positions, valuation and P&L.

Response

{
  "data": {
    "simulated": true,
    "cash": 24310.55,
    "equityValue": 81240.18,
    "totalValue": 105550.73,
    "pnl24h": 912.4,
    "totalPnl": 5550.73,
    "positions": [
      {
        "symbol": "NVDA",
        "tokenSymbol": "sNVDA",
        "quantity": 65,
        "avgCost": 171.22,
        "price": 185.18,
        "value": 12036.7,
        "allocation": 0.114
      }
    ]
  }
}

GET/api/v1/portfolio/history?range=3Mscope: read

Portfolio value series reconstructed from the ledger. Ranges: 1W, 1M, 3M, 1Y, ALL.

Transactions

GET/api/v1/transactionsscope: read

Ledger entries: deposits, trades, fees, distributions and transfers.

GET/api/v1/watchlistscope: read

The authenticated user's watchlist.

Webhooks

Webhooks deliver order fills, transfers, corporate actions and verification updates. Each delivery is signed with HMAC-SHA256 over `timestamp.body`; reject deliveries older than five minutes.

order.filled

{
  "id": "evt_…",
  "type": "order.filled",
  "created": "2026-10-03T14:30:05Z",
  "data": {
    "orderId": "ord_…",
    "symbol": "NVDA",
    "side": "BUY",
    "quantity": 2.5,
    "price": 179.95,
    "simulated": true
  }
}

Verifying a signature (Node.js)

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(rawBody: string, header: string, secret: string) {
  const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest();
  return timingSafeEqual(expected, Buffer.from(v1, "hex"));
}

WebSockets

Subscribe to real-time streams over a single connection. The API also serves quotes as Server-Sent Events at /api/stream/quotes, and clients fall back to polling when neither is reachable.

Endpoint

wss://api.xstockss.fun/markets

quotes

Top-of-book and last price per symbol

trades

Executions on supported venues

orderbook

Depth snapshots and incremental updates

portfolio

Valuation changes (authenticated)

orders

Order state transitions (authenticated)

{
  "type": "subscribe",
  "channel": "quotes",
  "symbols": [
    "NVDA",
    "AAPL"
  ]
}

Message

{
  "channel": "quotes",
  "simulated": true,
  "quotes": [
    {
      "symbol": "NVDA",
      "price": 185.01,
      "changePct24h": 0.0227,
      "timestamp": 1791011541150
    }
  ]
}

Blockchain

Token metadata per network: standard, decimals and contract address. Addresses are null until a contract is deployed — the API never returns placeholder addresses.

GET/api/v1/assets/{symbol}

See tokens[] for per-network configuration.

GET/api/v1/transparency

Reserve reconciliation snapshot, attestation reports and mint/burn events. In demo mode this is a demonstration dataset, flagged meta.demonstration.

Corporate Actions

GET/api/v1/corporate-actions/{symbol}

Dividends, splits, mergers and other events with token treatment. Returns an empty list and meta.providerConfigured=false until a reference-data feed is connected.

Errors & limits

Error envelope

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed",
    "details": [
      {
        "path": "limitPrice",
        "message": "Limit price is required for limit orders"
      }
    ]
  }
}

Bucket	Limit
auth	10 requests / 10 min
orders	30 requests / 1 min
write	60 requests / 1 min
read	300 requests / 1 min
contact	5 requests / 1h

Exceeding a limit returns 429 with a Retry-After header. Request bodies are capped at 32 KB.