Back to Documentation
Documentation

API Access

Programmatic access to the Velox swap engine. REST for order execution, WebSocket for real-time pricing, HMAC-signed authentication with granular rate limits.

Overview

The Velox API provides institutional and retail developers with direct access to the same swap infrastructure that powers the Velox web interface. Two transport protocols are available, each designed for a specific class of operation.

◎

REST API

Synchronous endpoints for quote requests, swap execution, and settlement status. All responses are JSON-encoded and delivered over HTTPS. Ideal for server-side integration and order-management workflows.

◇

WebSocket Stream

Persistent connection for real-time price feeds, order-book depth snapshots, and settlement confirmations. Frame-level compression and automatic reconnection with exponential backoff are built in.

Authentication

Every request to the Velox API must be authenticated with an API key and an HMAC-SHA256 signature. Credentials are provisioned through the Velox dashboard under Settings → API Keys. Each key is scoped to a specific environment (testnet or mainnet) and carries its own rate-limit tier.

HMAC Signature Construction

The signature is computed over the concatenation of timestamp + method + requestPath + body, using your API secret as the HMAC key. The timestamp must be within 30 seconds of server time to prevent replay attacks. 

# Construct the signing payload
TIMESTAMP=$(date +%s000)
METHOD="POST"
PATH="/v1/swap/quote"
BODY='{"fromToken":"USDT","toToken":"TRX","amount":"100"}'

PAYLOAD="${TIMESTAMP}${METHOD}${PATH}${BODY}"
SIGNATURE=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "$VELOX_API_SECRET" | awk '{print $2}')

# Include headers in the request
curl -X POST "https://api.velox.fi/v1/swap/quote" \
  -H "X-VLX-API-Key: ${VELOX_API_KEY}" \
  -H "X-VLX-Timestamp: ${TIMESTAMP}" \
  -H "X-VLX-Signature: ${SIGNATURE}" \
  -H "Content-Type: application/json" \
  -d "${BODY}"

REST API Reference

All REST endpoints are served from https://api.velox.fi. Requests and responses use JSON with Content-Type: application/json. The base endpoint for swaps is /v1/swap.

GET /v1/swap/quote

Returns a firm, time-limited quote for a USDT ↔ TRX swap. The quote includes the exact receive amount, effective exchange rate, gas sponsorship allocation, and an expiry timestamp after which the quote must be re-requested.

Example Request

curl -X POST "https://api.velox.fi/v1/swap/quote" \
  -H "X-VLX-API-Key: vlx_live_8fK2m..." \
  -H "X-VLX-Timestamp: 1724019200000" \
  -H "X-VLX-Signature: a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{
    "fromToken": "USDT",
    "toToken": "TRX",
    "amount": "500.00",
    "slippageBps": 50
  }'

Example Response

{
  "quoteId": "qt_8a7b3c9d",
  "fromToken": "USDT",
  "toToken": "TRX",
  "fromAmount": "500.00",
  "toAmount": "1515.00",
  "exchangeRate": "3.03",
  "gasSponsored": true,
  "gasCostTRX": "2.68",
  "platformFeeBps": 30,
  "effectivePrice": "1 USDT = 3.03 TRX",
  "expiresAt": 17240192015000,
  "slippageBps": 50,
  "minimumReceive": "1507.425"
}

Rate Limits

Rate limits are enforced per API key and measured across a sliding 60-second window. Exceeding the limit returns HTTP 429 with a Retry-After header indicating when the next request will be accepted. Higher-tier limits are available for institutional partners.

Tier REST RPM WebSocket Messages Swap Executions / Min Concurrent Connections Status
Sandbox 30 60 / min 2 1 Test Only
Standard 300 600 / min 20 3 Default
Professional 1,200 2,400 / min 60 10 Upgraded
Institutional 5,000 Unlimited 300 50 Apply

Getting Started

New to the Velox API? Follow these steps to execute your first swap programmatically in under five minutes.

01

Generate API Credentials

Log into the Velox dashboard, navigate to Settings → API Keys, and click Generate Key. Store the secret securely — it is shown only once.

02

Test Against Sandbox

Point your client to https://api.sandbox.velox.fi. The sandbox mirrors production behavior using testnet TRON tokens — no real value is transferred.

03

Request a Quote, Then Execute

Call /v1/swap/quote to lock in a rate, then call /v1/swap/execute with the quote ID within the expiry window. The transaction is submitted and confirmed within one TRON block (~3 seconds).

04

Monitor via WebSocket

Subscribe to wss://api.velox.fi/v1/ws with channel settlement_updates to receive real-time confirmations the moment your swap settles on-chain.

Full endpoint documentation, including pagination, error codes, and WebSocket channel descriptions, is available in the Velox API Reference (OpenAPI 3.1 spec). Contact api@velox.fi for institutional onboarding.