API Key Creation & Management

Create, list, update, and revoke GaiaEx API keys. Set IP whitelists, permissions, and view the full audit log.

AI AGENT READYEquip Claude Code, OpenAI Codex & Antigravity (`agy`) with Official GaiaEx Skills

CLAUDE CODESKILL.md

Claude SKILL.md

Drop-in Claude Code skill with HMAC-SHA256 signing, /fapi/v1 & /fapi/v2 schemas, and secret-redaction guardrails.

Raw ↗

OPENAI CODEXAGENTS.md

Codex AGENTS.md

Drop-in repository AGENTS.md for OpenAI Codex CLI — tick-size rules, rate-limit budgets, and self-custody boundaries.

Raw ↗

ANTIGRAVITYAGY.md

Antigravity AGY.md

Google Antigravity (agy) & Gemini agent spec with verified async Python WebSocket + REST execution templates.

Raw ↗

UNIVERSAL LLMllms.txt

/llms.txt Index

Single-URL machine-readable index of all GaiaEx documentation pages, OpenAPI 3.0 schema, and Postman collection.

Raw ↗

API Key Overview

GaiaEx API keys let trading bots and scripts authenticate via HMAC-SHA256 without exposing your wallet credentials. All key management — create, update, revoke — is done from the GaiaEx mobile app. Once you have a key, bots use it directly via the signed-request headers.

What an API key can do

API keys have exactly two permission scopes: read and trade. There is no withdrawal scope. API keys cannot deposit, withdraw, transfer on-chain, or swap — those actions require your embedded-wallet signature and a passkey step-up, and are only available in the mobile app. A compromised API key can trade and read your account data, but it cannot move funds off the platform.

Two prerequisites before you can create a key

Completed onboarding — you must have signed the wallet agent authorizations (EIP-712) from the GaiaEx mobile app at least once.
Placed at least one trade in the app — your account must have completed the trading handshake. Keys with trade permission cannot be issued to accounts that have never traded.

GET20/s IPhttps://openapi.gaiaex.com/v1/trade/api-keysSession

Create API Key

App-only

API keys are created, modified, and revoked in the GaiaEx app (passkey-gated). This operation cannot be performed via the public API — it is documented here for reference only.

Create a new API key. The API secret is returned only once in this response.

App only

This endpoint requires a passkey step-up challenge in addition to session authentication. In practice this means it must be called from the GaiaEx mobile app — the app handles the passkey challenge transparently. Calling this endpoint from a plain REST client or bot is not supported; bots cannot self-issue API keys.

To get an API key: open the GaiaEx app → Settings → API Keys → Create Key. Copy and store the secret immediately.

Authentication: Session JWT + passkey step-up (X-PASSKEY-TOKEN header injected by the app).

Request Body:

Field	Type	Required	Description
`label`	string	No	Descriptive label for this key (e.g. "grid-bot-prod")
`permissions`	array	No	`"read"` and/or `"trade"`. Defaults to `["read"]`.
`ip_whitelist`	array	No	Allowed IPs or CIDR blocks. Omit for unrestricted access.
`expires_days`	int	No	Auto-expire after N days. Omit for no expiration.

Example Request:

{
  "label": "trading-bot-v1",
  "permissions": ["read", "trade"],
  "ip_whitelist": ["203.0.113.50"],
  "expires_days": 90
}

Response (200 OK):

{
  "api_key": "a1b2c3d4e5f6789012345678abcdef01",
  "api_secret": "e87d3c78493c3c77d207ceda1a3677e7b23eebbe64be790987014d27b3fd2b9e",
  "label": "trading-bot-v1",
  "permissions": ["read", "trade"],
  "ip_whitelist": ["203.0.113.50"],
  "created_at": "2026-04-01T12:00:00Z",
  "expires_at": "2026-06-30T12:00:00Z",
  "message": "Save your API secret now. It will NOT be shown again."
}

Store the secret now

The api_secret is shown only in this response and is never retrievable again. Copy it to a secure location immediately. If lost, revoke the key and create a new one.

Error codes:

Code	Reason
400	Invalid permission value, invalid IP/CIDR, or maximum key limit reached (max 10 keys per user)
401	Missing or expired session token
403	Passkey step-up failed, or account has not completed trading handshake (required for `trade` permission)
503	API key system not available

GET20/s IPhttps://openapi.gaiaex.com/v1/trade/api-keysSession

List API Keys

Returns all API keys for the authenticated user. Secrets are never included in this response.

Authentication: Session JWT.

Response (200 OK):

{
  "keys": [
    {
      "api_key": "a1b2c3d4e5f6789012345678abcdef01",
      "label": "trading-bot-v1",
      "permissions": ["read", "trade"],
      "ip_whitelist": ["203.0.113.50"],
      "created_at": "2026-04-01T12:00:00Z",
      "expires_at": "2026-06-30T12:00:00Z",
      "last_used_at": "2026-04-01T15:30:00Z",
      "is_active": true
    }
  ]
}

GET20/s IPhttps://openapi.gaiaex.com/v1/trade/api-keysSession

Update API Key

App-only

API keys are created, modified, and revoked in the GaiaEx app (passkey-gated). This operation cannot be performed via the public API — it is documented here for reference only.

Update the label, permissions, or IP whitelist of an existing key. Requires passkey step-up — use the GaiaEx app.

Authentication: Session JWT + passkey step-up.

Path Parameters:

Parameter	Type	Description
`api_key`	string	The API key to update

Request Body (all fields optional):

Field	Type	Description
`label`	string	New label
`permissions`	array	New permissions list (`"read"`, `"trade"`)
`ip_whitelist`	array	New IP whitelist. Pass empty array to remove restriction.

Response (200 OK):

{
  "success": true,
  "api_key": "a1b2c3d4e5f6789012345678abcdef01",
  "updated_fields": ["permissions"]
}

GET20/s IPhttps://openapi.gaiaex.com/v1/trade/api-keysSession

Revoke API Key

App-only

API keys are created, modified, and revoked in the GaiaEx app (passkey-gated). This operation cannot be performed via the public API — it is documented here for reference only.

Permanently revoke a single API key. Requires passkey step-up — use the GaiaEx app. This action is irreversible.

Authentication: Session JWT + passkey step-up.

Path Parameters:

Parameter	Type	Description
`api_key`	string	The API key to revoke

Response (200 OK):

{
  "success": true,
  "message": "API key revoked"
}

GET20/s IPhttps://openapi.gaiaex.com/v1/trade/api-keysSession

Revoke All API Keys

App-only

API keys are created, modified, and revoked in the GaiaEx app (passkey-gated). This operation cannot be performed via the public API — it is documented here for reference only.

Revoke all active API keys for the authenticated user in one call. Use this for emergency lockdown. Requires passkey step-up — use the GaiaEx app.

Authentication: Session JWT + passkey step-up.

Response (200 OK):

{
  "success": true,
  "revoked_count": 3
}

GET20/s IPhttps://openapi.gaiaex.com/v1/trade/api-keys/{api_key}/auditSession

API Key Audit Log

Returns the lifecycle event log for a specific API key — records create, update, and revoke actions on this key. Does NOT log per-request API call traffic.

Authentication: Session JWT.

Path Parameters:

Parameter	Type	Description
`api_key`	string	The API key to inspect

Query Parameters:

Parameter	Type	Default	Max	Description
`limit`	int	20	100	Number of audit entries to return

Response (200 OK):

{
  "api_key": "a1b2c3d4e5f6789012345678abcdef01",
  "audit": [
    {
      "action": "key_created",
      "ip_address": "203.0.113.50",
      "created_at": "2026-04-01T15:30:00Z",
      "details": "Key created with permissions: [read, trade]"
    }
  ],
  "count": 1
}

Parameters

Name	Type	Required	Description
api_key	string	Yes	API key to audit

api_key

stringRequired

API key to audit