Builder API Keys

Builder API keys link your application to the Openfish CLOB, enabling order attribution, gasless relayer transactions, and volume tracking.

---

Prerequisites

A standard L2 API key is required before you can generate a builder key. See Getting Started for instructions on obtaining L2 credentials.

---

Creating a Builder API Key

POST /auth/builder-api-key

L2 authentication is required. Send a JSON body containing your chosen builder identifier.

Request:

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

Response:

{
  "apiKey": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "secret": "base64-encoded-secret",
  "passphrase": "generated-passphrase",
  "builderId": "my-trading-app"
}

Important: The secret and passphrase appear only once during creation. Store them immediately in a secrets manager or environment variables. If you lose them, the only option is to create a new key.

Rust Example

use reqwest::Client;
use serde_json::json;

let response = Client::new()
    .post("https://api.openfish.fun/auth/builder-api-key")
    .header("OPENFISH_API_KEY", &api_key)
    .header("OPENFISH_SECRET", &secret)
    .header("OPENFISH_PASSPHRASE", &passphrase)
    .header("OPENFISH_TIMESTAMP", &timestamp)
    .header("OPENFISH_SIGNATURE", &hmac_signature)
    .json(&json!({ "builderId": "my-trading-app" }))
    .send()
    .await?;

let creds: serde_json::Value = response.json().await?;
println!("Builder API Key: {}", creds["apiKey"]);
println!("Secret: {}", creds["secret"]);
println!("Passphrase: {}", creds["passphrase"]);

---

Listing Builder API Keys

GET /auth/builder-api-key

L2 authentication is required. Returns every builder API key tied to your account.

Response:

{
  "apiKeys": [
    {
      "apiKey": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "builderId": "my-trading-app",
      "createdAt": "2026-04-01T12:00:00Z"
    }
  ]
}

Note: the list endpoint does not return secrets or passphrases.

---

Revoking a Builder API Key

DELETE /auth/builder-api-key

L2 authentication is required. Specify the API key to revoke as a query parameter.

DELETE /auth/builder-api-key?apiKey=a1b2c3d4-e5f6-7890-abcd-ef1234567890

Response: {} on success.

If the key does not exist or belongs to a different account, the server responds with 404 Not Found.

---

Environment Variables

Keep your builder credentials secure by storing them as environment variables:

export OPENFISH_BUILDER_API_KEY="a1b2c3d4-e5f6-7890-abcd-ef1234567890"
export OPENFISH_BUILDER_SECRET="your-secret"
export OPENFISH_BUILDER_PASSPHRASE="your-passphrase"
export OPENFISH_BUILDER_ID="my-trading-app"

Load them in your application:

let builder_api_key = std::env::var("OPENFISH_BUILDER_API_KEY")?;
let builder_secret = std::env::var("OPENFISH_BUILDER_SECRET")?;
let builder_passphrase = std::env::var("OPENFISH_BUILDER_PASSPHRASE")?;
let builder_id = std::env::var("OPENFISH_BUILDER_ID")?;

---

Key Management Best Practices

Practice	Description
Never commit credentials	Add .env files to .gitignore
Use environment variables	Load from env vars, never hardcode
Use a secrets manager	AWS Secrets Manager, HashiCorp Vault, etc. for production
Separate keys per environment	Use different keys for development, staging, and production
Rotate regularly	Revoke old keys and create new ones periodically
Keep server-side only	Never expose builder credentials in client-side code

---

Error Reference

Endpoint	Error	Description
POST /auth/builder-api-key	400 Bad Request	builderId required — the request body is missing or empty
POST /auth/builder-api-key	401 Unauthorized	L2 authentication failed
POST /auth/builder-api-key	500 Internal Server Error	could not create builder api key
GET /auth/builder-api-key	500 Internal Server Error	could not get builder api keys
DELETE /auth/builder-api-key	400 Bad Request	invalid apiKey — not a valid UUID
DELETE /auth/builder-api-key	404 Not Found	builder API key not found

---

Next Steps

• Builder Overview — How the Builder Program works.
• Tiers — Rate limits and how to upgrade.