Enabling API access

Before an API key can trade a subaccount, that subaccount must be enabled for API access and the key must be granted permissions. A subaccount needs three approvals in place:

Approval	What it authorizes
API Access	The subaccount is opted in to programmatic (API) trading.
On-Chain Permissions	On-chain approval allowing API-driven actions on the subaccount.
Solver Permission	The solver is authorized to execute on your behalf (required for instant execution).

There are two ways to set this up.

Method 1 — Frontend (recommended)

Do it once in the Carbon app: beta.carbon.inc/account/api-management

1. Select the account (crypto or tradfi subaccount) from the dropdown at the top of the page.

2. Under Account Permissions, click Enable. This walks you through approving all three: API Access, On-Chain Permissions, and Solver Permission. If any later shows as not enabled, use Revalidate.

3. Click Create API to mint an API key, then set its permissions.

4. Copy the key secret — it's shown only once. Store it securely.

Your keys appear under Your APIs with their status; use Manage to adjust permissions or revoke a key.

This is the recommended path because the app handles the wallet signatures and on-chain approvals for you. Once a subaccount is enabled here, your API keys can trade it without any further wallet interaction.

Method 2 — Programmatic (API)

You can perform the gateway-side setup over the API with a session JWT (see Authentication):

# 1. Create an API key
POST /v1/api-keys/create

# 2. Enable API access on the subaccount
POST /v1/account-auth/subaccount/toggle-access
{ "subaccountAddress": "0x…", "chainId": 42161, "enable": true }

# 3. Delegate permissions to the key
POST /v1/account-auth/delegate-access
{ "subaccountAddress": "0x…", "apiKeyIdentifier": "…",
  "permissions": ["OPEN_POSITION", "CLOSE_POSITION"] }

# 4. (For instant execution) register a solver instant-action token
POST /v1/account-auth/instant-action/token

Permissions (AllowedPermission): ALL, OPEN_POSITION, CLOSE_POSITION, CANCEL_POSITION, VIEW_DETAILS.

The On-Chain and Solver approvals require signatures from the owning wallet. Most integrators complete the enabling step once in the frontend and then use API keys for everything else — even when scripting the rest.

Verify and revoke

Action	Endpoint
Check a subaccount's access	GET /v1/account-auth/verify?subaccountAddress=0x…
List a subaccount's delegations	GET /v1/account-auth/subaccount/list-api-delegations
Revoke a delegation	DELETE /v1/account-auth/delegation/{subaccountAddress}/{apiKeyIdentifier}

A key that attempts an action it wasn't granted is rejected with 403.