Authentication

Public data endpoints do not require an API key. Authenticated endpoints require providing your API key in the apikey HTTP request header. The same key works for Opinion OpenAPI, Opinion Websocket, and Opinion CLOB SDK.

Getting an API key

You can create your own API key instantly by signing an EIP-712 message with your wallet — no application form or approval needed.

Prerequisites:

• Your wallet must be a registered Opinion account with a trading wallet enabled — connect the wallet on opinion.trade and complete onboarding first.

• Each wallet holds one active API key at a time.

The three Auth endpoints (POST / GET / DELETE /auth/api-key) are authenticated by wallet signature only — no API key required. Every request carries three headers: OPINION_ADDRESS (the signing wallet address), OPINION_SIGNATURE (EIP-712 signature) and OPINION_TIMESTAMP (Unix timestamp in seconds, must match the signed timestamp field).

Signing the request

Sign the following EIP-712 typed data with your wallet's private key:

{
  "types": {
    "EIP712Domain": [
      { "name": "name", "type": "string" },
      { "name": "version", "type": "string" },
      { "name": "chainId", "type": "uint256" }
    ],
    "OpinionApiKeyAuth": [
      { "name": "walletAddress", "type": "address" },
      { "name": "action", "type": "string" },
      { "name": "timestamp", "type": "string" }
    ]
  },
  "primaryType": "OpinionApiKeyAuth",
  "domain": {
    "name": "Opinion OpenAPI",
    "version": "1",
    "chainId": 56
  },
  "message": {
    "walletAddress": "0xYourWalletAddress",
    "action": "create",
    "timestamp": "1753690000"
  }
}

• action must match the endpoint: create for POST, get for GET, delete for DELETE. A signature for one action cannot be reused for another.

• Signatures expire after 5 minutes. create and delete signatures are single-use — sign a fresh message for each attempt. get signatures can be retried within the window.

Example

import { Wallet } from "ethers";

const wallet = new Wallet(process.env.PRIVATE_KEY);
const timestamp = Math.floor(Date.now() / 1000).toString();

const signature = await wallet.signTypedData(
  { name: "Opinion OpenAPI", version: "1", chainId: 56 },
  {
    OpinionApiKeyAuth: [
      { name: "walletAddress", type: "address" },
      { name: "action", type: "string" },
      { name: "timestamp", type: "string" },
    ],
  },
  { walletAddress: wallet.address, action: "create", timestamp }
);

const res = await fetch("https://openapi.opinion.trade/openapi/auth/api-key", {
  method: "POST",
  headers: {
    OPINION_ADDRESS: wallet.address,
    OPINION_SIGNATURE: signature,
    OPINION_TIMESTAMP: timestamp,
  },
});
console.log(await res.json());
// { "errno": 0, "errmsg": "", "result": { "apiKey": "…", "walletAddress": "0x…" } }

Response codes

Unlike the data endpoints, the Auth endpoints return HTTP 200 with the outcome in an errno / errmsg / result envelope — always check errno:

errno	Meaning
0	Success
11004	Self-service key issuance is temporarily disabled
11005	Wallet is not a registered Opinion account — connect it on opinion.trade first
11009	API key already exists — use GET to retrieve it
11010	No API key found for this wallet
11011	Invalid signature
11012	Signature expired
11013	Signature already used — sign a fresh message

Key activation timing

• A newly created key becomes active at the gateway within about 15 seconds. If your first requests return 401, simply retry — no backoff needed.

• After DELETE, the old key stops working within about 10 seconds.

• To rotate a key, call DELETE then POST, and plan for up to ~15 seconds during which neither key is usable.

If you lose your key, call GET at any time to retrieve it. If your key is compromised, DELETE it and create a new one.