API Overview

HyperQuote exposes two API surfaces for programmatic access: a REST API for RFQ management and data queries, and a WebSocket relay for real-time RFQ broadcasting and quote collection.

Who This Is For

• Makers building automated quoting bots that receive RFQs and submit quotes programmatically.
• Takers who want to create and manage RFQs via API instead of the web UI.
• Integrators building applications on top of HyperQuote liquidity.
• Data consumers who need access to the live feed, leaderboard, or fill history.

API Surfaces

Base URLs

REST API

Production: https://hyperquote.xyz/api/v1
Local:      http://localhost:3000/api/v1

WebSocket Relay

Production: wss://relay.hyperquote.xyz
Local:      ws://127.0.0.1:8080

Versioning

All REST API endpoints use the /api/v1/ prefix. Breaking changes will be introduced under a new version prefix (e.g. /api/v2/). Non-breaking additions (new fields, new endpoints) may be added to v1 without a version bump.

Response Format

All API responses use JSON (application/json). Include the Content-Type: application/json header in POST requests.

curl -X POST https://hyperquote.xyz/api/v1/quotes \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Successful Responses

Successful responses return an HTTP 2xx status code with a JSON body. The structure varies by endpoint but always contains the relevant data at the top level.

Error Responses

All errors follow a consistent JSON format:

{
  "error": "Human-readable error description"
}

HTTP status codes follow standard conventions. See Error Codes for the complete reference.

Pagination

List endpoints use cursor-based pagination for efficient traversal of large result sets.

Paginated responses include:

{
  "items": [ ... ],
  "nextCursor": "abc123-def456"
}

When nextCursor is null, there are no more results. Pass the nextCursor value as the cursor query parameter in the next request to fetch the next page.

Authentication

The REST API supports two authentication methods:

1. Bearer Token — For agent API access. Keys are prefixed with hq_live_.
2. Wallet Signature — For operations tied to a specific wallet address (EIP-191).

Public endpoints (leaderboard, feed, badges, profile) do not require authentication. See Authentication for details.

Endpoint Categories

Public (No Auth Required)

Agent API (Bearer Token Required)

Rate Limiting

All endpoints are rate-limited. Rate limit headers are included in responses:

Retry-After: 30

See Rate Limits for per-endpoint limits.

Edge Cases

Related Pages

• Authentication — Bearer tokens and wallet signatures
• RFQ Endpoints — Create and query RFQs
• Quote Endpoints — Submit and retrieve quotes
• Relay WebSocket Protocol — Real-time connection protocol
• Error Codes — Full error reference
• Rate Limits — Per-endpoint rate limits