Helios uses API keys and request signing to authenticate and authorize requests.
All requests must be authenticated before reaching execution or simulation layers.

API Keys

Each Helios account is issued one or more API keys.

• API keys identify your application

• Keys should be kept secret

• Separate keys are recommended per environment

API keys are passed via the Authorization header.

Authorization: Bearer YOUR_API_KEY

Request Signing

In addition to API keys, Helios requires request signing to ensure integrity and prevent replay attacks.

Each request is signed using:

• Request payload

• Timestamp

• Your API secret

Example: Signing a Request (Node.js)

import crypto from "crypto";

const timestamp = Date.now().toString();
const payload = JSON.stringify(body);

const signature = crypto
  .createHmac("sha256", process.env.HELIOS_API_SECRET)
  .update(timestamp + payload)
  .digest("hex");

Attach both the timestamp and signature as headers.

X-Helios-Timestamp: 1737048129
X-Helios-Signature: ab34f9

Requests without valid signatures are rejected.

Permission Scopes

API keys are scoped to limit access.

Common scopes include:

• simulate:read

• execute:write

• routes:read

• risk:read

Scopes are enforced at request time.
Requests using insufficient permissions return 403 Forbidden.

Example: Scoped Key Usage

// Requires execute:write
await helios.execute({ ...params });

Rate Limits

Rate limits are enforced per API key.

Limits vary by:

• Environment

• Endpoint type

• Account tier

When a rate limit is exceeded, the API returns:

429 Too Many Requests

Rate limit headers are included in every response.

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 87

Clients should implement retries with backoff.

Environments

Helios provides isolated environments for development and production.

• testnet — for testing and simulations

• mainnet — for live execution

Environment selection is configured at client initialization.

const helios = new Helios({
  apiKey: process.env.HELIOS_API_KEY,
  environment: "testnet",
});

Keys are environment-specific and cannot be reused across environments.

Authentication Errors

Authentication failures return explicit error codes.

{
  "error": {
    "code": "AUTHENTICATION_FAILED",
    "message": "Invalid API key or signature"
  }
}

Common causes include:

• Missing headers

• Incorrect signatures

• Expired timestamps

• Insufficient scopes