Authenticate with your delegate wallet and obtain JWT credentials for REST and WebSocket

Connect to API

Use this guide to authenticate with Cascade and get a JWT bearer token for REST and WebSocket access.

Requirements

Before continuing, complete:

Authenticate with the server

Use the widget below to quickly get an API key for your delegate account. Once authenticated, you can test the API here.

No API key

Manual authentication steps

1. Request a challenge

curl "https://engine.cascade.cooking/auth?account=<DEPOSIT_ADDRESS>"

2. Sign and POST proof

Sign signing_payload using EIP-191 (eth_sign / personal sign)
POST { message, signature, server_signature } back to /auth
Store returned { token, claims }

3. Use JWT for REST

Authorization: Bearer <token>

4. Authenticate WebSocket

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "auth",
  "params": { "bearer": "<token>" }
}

JavaScript example (viem)

import { createWalletClient, custom } from "viem";

const ethereumProvider = /* browser wallet, WalletConnect, embedded signer, etc. */;
const wallet = createWalletClient({ transport: custom(ethereumProvider) });

const depositAddress = "0x..."; // Cascade account/deposit address
const [delegateAddress] = await wallet.getAddresses();

const challenge = await fetch(
  `https://engine.cascade.cooking/auth?account=${depositAddress}`,
).then((res) => res.json());

const signature = await wallet.signMessage({
  account: delegateAddress,
  message: challenge.signing_payload,
});

const session = await fetch("https://engine.cascade.cooking/auth", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    message: challenge.message,
    signature,
    server_signature: challenge.server_signature,
  }),
}).then((res) => res.json());

const token = session.token;

await fetch("https://engine.cascade.cooking/account/orders", {
  headers: { Authorization: `Bearer ${token}` },
});

Python example (web3.py)

import os
import requests
from eth_account import Account
from eth_account.messages import encode_defunct

BASE_URL = "https://engine.cascade.cooking"
DEPOSIT_ADDRESS = os.environ["DEPOSIT_ADDRESS"]
delegate = Account.from_key(os.environ["DELEGATE_PRIVATE_KEY"])

challenge = requests.get(
    f"{BASE_URL}/auth",
    params={"account": DEPOSIT_ADDRESS},
    timeout=10,
).json()

message = encode_defunct(text=challenge["signing_payload"])
signature = Account.sign_message(message, private_key=delegate.key).signature.hex()

session = requests.post(
    f"{BASE_URL}/auth",
    json={
        "message": challenge["message"],
        "signature": signature,
        "server_signature": challenge["server_signature"],
    },
    timeout=10,
).json()

token = session["token"]

requests.get(
    f"{BASE_URL}/account/orders",
    headers={"Authorization": f"Bearer {token}"},
    timeout=10,
)

Connect to API

On this page