Auth endpoints

All endpoints are served from the CLOB server at https://api.openfish.fun.

---

POST /auth/api-key

Authentication: L1 (wallet signature)

Create a new CLOB API key. Requires L1 auth headers with a wallet signature.

Invitation code required. Openfish is currently invite-only. You must include a valid invitation code when creating your first API key. Codes are issued by the Openfish team after waitlist approval. Each code is single-use and has an expiration date.

L1 Auth Headers:

Header	Description
OPENFISH_ADDRESS	Ethereum address
OPENFISH_TIMESTAMP	Unix timestamp
OPENFISH_NONCE	Nonce (integer)
OPENFISH_SIGNATURE	EIP-712 wallet signature
OPENFISH_INVITATION_CODE	Invitation code (e.g. AF3K-X9M2). Required on first key creation.

How to get an invitation code:

1. Join the waitlist: POST /waitlist with your email.
2. Once approved, you’ll receive a code (format: XXXX-XXXX) via email or from the Openfish team.
3. Pass the code in the OPENFISH_INVITATION_CODE header when calling this endpoint.

Response (200):

{
  "apiKey": "9180014b-33c8-9240-a14b-bdca11c0a465",
  "secret": "base64-encoded-secret",
  "passphrase": "random-passphrase"
}

Errors: 400 invalid address or invalid/expired invitation code, 409 key already exists for this nonce.

---

DELETE /auth/api-key

Authentication: L2 (HMAC)

Delete the current API key.

Response (200): {}

Errors: 404 key not found.

---

GET /auth/api-keys

Authentication: L2 (HMAC)

List all API keys for the authenticated address.

Response (200):

{
  "apiKeys": [
    "9180014b-33c8-9240-a14b-bdca11c0a465",
    "a2b3c4d5-e6f7-8901-bcde-f12345678901"
  ]
}

---

GET /auth/derive-api-key

Authentication: L1 (wallet signature)

Retrieve an existing API key by address and nonce. Returns the same apiKey, secret, and passphrase as the create endpoint.

Errors: 404 no key found for this address and nonce.

---

GET /auth/ban-status/closed-only

Authentication: L2 (HMAC)

Check if the account is restricted to close-only mode.

Response (200):

{ "closed_only": false }

---

POST /auth/builder-api-key

Authentication: L2 (HMAC)

Create a builder API key.

Request Body:

{ "builderId": "my-trading-bot" }

Response (200):

{
  "apiKey": "b3c4d5e6-f7a8-9012-cdef-234567890abc",
  "secret": "base64-encoded-secret",
  "passphrase": "random-passphrase",
  "builderId": "my-trading-bot"
}

Errors: 400 builderId required.

---

GET /auth/builder-api-key

Authentication: L2 (HMAC)

List all builder API keys for the authenticated address.

Response (200):

{
  "apiKeys": [
    {
      "apiKey": "b3c4d5e6-f7a8-9012-cdef-234567890abc",
      "builderId": "my-trading-bot",
      "createdAt": "2026-04-09T12:00:00Z"
    }
  ]
}

---

DELETE /auth/builder-api-key

Authentication: L2 (HMAC)

Delete a builder API key. Pass ?apiKey=<uuid> as a query parameter.

Response (200): {}

Errors: 400 invalid apiKey, 404 not found.

---

GET /balance-allowance

Authentication: L2 (HMAC)

Parameters:

Parameter	Type	Required	Description
signature_type	integer	No	0 (EOA), 1 (OPENFISH_PROXY), or 2 (GNOSIS_SAFE). Determines which address to query balances for. Default: 0

Returns the USDC collateral balance and all conditional token balances for the authenticated user.

Response (200):

{
  "balance": "10000.00",
  "allowances": {
    "52114319501245...": "500.00",
    "65818619657568...": "250.00"
  }
}

---

GET /balance-allowance/update

Authentication: L2 (HMAC)

Trigger a balance reconciliation from order/trade history.

Response (200):

{
  "balance": "10000.00",
  "net_usdc_taker": "-3200.50",
  "net_usdc_maker": "1800.25"
}

---

GET /notifications

Authentication: L2 (HMAC)

List notifications for the authenticated user.

Response (200):

[
  {
    "type": "TRADE_CONFIRMED",
    "owner": "9180014b-33c8-9240-a14b-bdca11c0a465",
    "payload": { "tradeId": "..." }
  }
]

---

DELETE /notifications

Authentication: L2 (HMAC)

Delete all notifications for the authenticated user.

Response (200): {}