API Key Creation & Management

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

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.

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.

POST https://openapi.gaiaex.com/v1/trade/api-keys

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

List API Keys

GET https://openapi.gaiaex.com/v1/trade/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
    }
  ]
}

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.

PATCH https://openapi.gaiaex.com/v1/trade/api-keys/{api_key}

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"]
}

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.

DELETE https://openapi.gaiaex.com/v1/trade/api-keys/{api_key}

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"
}

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.

DELETE https://openapi.gaiaex.com/v1/trade/api-keys/all

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
}

API Key Audit Log

GET https://openapi.gaiaex.com/v1/trade/api-keys/{api_key}/audit

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
}