API Reference
Data Types

Data Types & Conventions

Decimal strings

All prices, sizes, and spreads are returned as strings, never floats. This preserves decimal precision that would be lost in JSON number parsing.

{
  "target_size": "2.5",
  "target_spread": "0.01",
  "filled_size": "1.25"
}

Use a decimal library client-side, e.g.:

  • Python: decimal.Decimal
  • JavaScript: bignumber.js, big.js, or decimal.js
  • Go: shopspring/decimal

Do not parse decimal strings as float64 / Number. You'll lose precision on values like 0.1 + 0.2.

Timestamps

All timestamps are RFC 3339 in UTC:

"2026-03-12T13:06:58Z"

The Z suffix is always present (never an offset like +00:00 or -05:00). Time zones in your local UI are your problem; the API speaks UTC.

Wallet addresses

Ethereum-style hex, always lowercase, with 0x prefix:

"0xYourWalletAddressHere"

The API normalizes mixed-case input to lowercase on storage. Your queries should also use lowercase to avoid mismatches.

Exchange identifiers

Lowercase, exactly as listed:

IdentifierExchange
hyperliquidHyperliquid
extendedExtended (x10)
lighterLighter (zkLighter)
orderlyOrderly Network
asterAster (asterdex)
hl_xyztrade[xyz] (Hyperliquid builder DEX)

The API only format-checks exchange names (alphanumeric/underscore) at submission time; an unrecognized exchange fails slightly later with a credential-lookup error ("no active credentials for wallet ... on ..."), not a dedicated validation error.

Market symbols

The market field in trade creation uses canonical symbols (e.g. BTC, ETH, HYPE, SOL). Spreadr translates these into the venue-specific symbols at execution time.

Get the full list of available canonical symbols + per-exchange mappings from Available Markets.

UUIDs

trade_id is a v4 UUID, 36 characters including hyphens:

"00000000-0000-0000-0000-000000000000"

User-supplied idempotency keys must match ^[a-zA-Z0-9_-]{1,128}$ — alphanumeric, hyphen, underscore only (a UUID works).

Enum values

All enums are lowercase strings:

  • spread_condition — gte, gt, lte, lt, eq
  • maker_leg — long, short
  • size_type — base, notional
  • spread_type — absolute (raw USD price difference), percentage (% of hedge reference price), bps (basis points of hedge reference price), ticks (multiples of the coarser leg's tick size)
  • execution_type — currently only maker_taker
  • Trade status — pending, validating, active, paused, recovering, completed, canceled, rejected, failed

Pagination

The current API does not paginate. List endpoints return the most recent 50 items unconditionally. If/when pagination is added, it'll use cursor-based parameters (since, limit) — not page numbers.

Versioning

Everything is under /api/v1. Breaking changes will go under /api/v2; non-breaking additions (new optional fields, new endpoints) will land in /api/v1 without a version bump.

ErrorsTroubleshooting