Security Best Practices

API key security is your responsibility. A compromised key can execute trades against your deposited balance and read your account data. It cannot move funds off the platform — withdrawals, deposits, and on-chain transfers all require the user's embedded-wallet signature plus a passkey step-up, which are only available in the mobile app. This guide covers battle-tested practices used by institutional trading desks.

Store credentials as environment variables, not in a file that lives in your project directory. This is the standard approach for local scripts, CI/CD pipelines, Docker containers, and cloud servers.

Step 1: Export the variables

# Set in your shell profile (~/.bashrc, ~/.zshrc), systemd EnvironmentFile, or CI/CD secrets manager — not a project file
export GAIAEX_API_KEY="a1b2c3d4e5f6789012345678abcdef00"
export GAIAEX_API_SECRET="s3cr3t_k3y_n3v3r_sh4r3_th1s"
export GAIAEX_ADDRESS="0xA6E3c04eF78427b5B53F43CDBA881d7E15B0bccD"

Step 2: Read them in your code

Python:

import os

API_KEY = os.environ["GAIAEX_API_KEY"]
API_SECRET = os.environ["GAIAEX_API_SECRET"]
ADDRESS = os.environ["GAIAEX_ADDRESS"]

JavaScript / Node.js:

const API_KEY = process.env.GAIAEX_API_KEY;
const API_SECRET = process.env.GAIAEX_API_SECRET;
const ADDRESS = process.env.GAIAEX_ADDRESS;

Rust:

let api_key = std::env::var("GAIAEX_API_KEY")?;
let api_secret = std::env::var("GAIAEX_API_SECRET")?;
let address = std::env::var("GAIAEX_ADDRESS")?;

For production trading bots and servers, go one step further than environment variables: pull credentials at runtime from a managed secrets service rather than setting them as plain shell exports. This adds encryption at rest, access auditing, and rotation without redeploying code.

Typical pattern: your process boots, calls the secrets service with an IAM role (no static credential needed to fetch the secret itself), receives the API key/secret in memory, and never writes it to disk.

Storage Options Compared

Lock your API key to specific IP addresses. Even if the key leaks, it cannot be used from unauthorized locations.

{
    "ip_whitelist": ["203.0.113.50", "198.51.100.0/24"]
}

Configure IP whitelisting when creating an API key via the GaiaEx mobile app. (POST /api-keys requires passkey step-up and is effectively app-only.)

GaiaEx API keys support granular permissions. Only grant the minimum permissions needed.

Recommendation:

• Monitoring scripts → ["read"] only
• Trading bots → ["read", "trade"]
• Never create "all permissions" keys unless absolutely necessary

Rotate API keys regularly — especially after team member departures, suspected leaks, or security incidents.

Rotation Procedure

1. Create a new key via the GaiaEx app or POST /api-keys (note: POST /api-keys requires a passkey step-up challenge and is effectively app-only — bots cannot self-issue keys)
2. Update your credential store — environment variables or secrets manager — with the new key
3. Verify the new key works (call GET /time or GET /health)
4. Revoke the old key via DELETE /api-keys/{api_key}

Recommended rotation schedule:

Monitor your API key activity for unauthorized access.

• Check the audit log via GET /api-keys/{api_key}/audit — shows lifecycle events (created, updated, revoked) for this key. Per-request call logs are not available.
• Monitor order history — unexpected orders may indicate compromised keys
• Set up alerts — use User Data Stream WebSocket to get real-time notifications of trades and balance changes

What to Watch For