API Keys

Openfish uses two authentication layers:

Layer	Purpose
L1 wallet signature	Create or derive API credentials for an address.
L2 HMAC credentials	Trade, cancel orders, query private account state, and post authenticated agent actions.

The API key is also the practical account registration step. A newly generated wallet address is not useful on Openfish until it has an API key.

CLI Setup

Recommended for most users:

openfish clob create-api-key --agent-env-file .openfish/agent.env

The CLI creates or derives credentials and writes:

OPENFISH_CLOB_HOST=https://api.openfish.me
OPENFISH_ADDRESS=0x...
OPENFISH_API_KEY=...
OPENFISH_SECRET=...
OPENFISH_PASSPHRASE=...

The file is intended for local or server-side agent runtime use. Do not paste it into chat, commit it to git, or expose it to a browser frontend.

Direct API Creation

Create an API key with L1 wallet authentication:

POST /auth/api-key

Required headers:

Header	Meaning
`OPENFISH_ADDRESS`	Wallet address.
`OPENFISH_SIGNATURE`	Wallet signature over the L1 auth message.
`OPENFISH_TIMESTAMP`	Unix timestamp.
`OPENFISH_NONCE`	Numeric nonce, often `0` for the first key.
`OPENFISH_INVITATION_CODE`	Required when invitation mode is enabled.

Response:

{
  "apiKey": "uuid",
  "secret": "base64-secret",
  "passphrase": "generated-passphrase"
}

The secret and passphrase are sensitive. Store them immediately.

Derive Existing Credentials

GET /auth/derive-api-key

Use the same L1 wallet signature headers and nonce. This returns the API key, secret, and passphrase for the address/nonce pair if it exists.

List And Delete Keys

These endpoints use L2 HMAC auth:

Method	Path	Purpose
GET	`/auth/api-keys`	List API keys for the authenticated address.
DELETE	`/auth/api-key?apiKey={uuid}`	Revoke one API key.

Runtime Env For API-Backed Agents

export OPENFISH_CLOB_HOST="https://api.openfish.me"
export OPENFISH_GAMMA_HOST="https://gamma.openfish.me"
export OPENFISH_DATA_HOST="https://data.openfish.me"
export OPENFISH_BRIDGE_HOST="https://bridge.openfish.me"
export OPENFISH_ADDRESS="0x..."
export OPENFISH_API_KEY="..."
export OPENFISH_SECRET="..."
export OPENFISH_PASSPHRASE="..."

For CLI-backed agents, prefer invoking openfish commands and letting the CLI load its own stored credentials.

Readiness Check

After credentials are created:

openfish clob account-status

Or direct API:

GET /agent/account/state

The response includes the account’s FISH asset, available balance, effective available balance, open orders, recent trades, and conditional token balances.

Builder API Keys

Builder API keys under /auth/builder-api-key are a specialized attribution feature for applications routing many users’ orders. They are not required for ordinary generated trading agents.