Skip to main content
Session keys are coming soon and are not live on https://api.futuur.com. All paths below are relative to the API base URL, for example /v2.0/me/session-delegations/prepare/. Where session keys are off, every endpoint on this page returns 404.
A session key lets a client sign orders without asking the owner wallet each time. You sign one delegation with the owner wallet. After that, a throwaway key signs each LimitOrderIntent. For what a session key is and which limits apply, read Session keys first.
Most API traders do not need this. If your program already signs every order with your own owner key, a session key gains you nothing. You need the owner key to sign the delegation, and your program already holds it. Use session keys in clients where the owner wallet is interactive: a browser wallet, a hardware wallet, or a mobile wallet where a person approves each signature.

Prerequisites

Everything in Place an on-chain order, plus:
  1. A registered, deployed Safe, with trading enabled for the currency.
  2. HMAC public and private keys for L2 request signing. See Get your API keys.
  3. The owner wallet, available once to sign the delegation.
  4. An on-chain currency (OOM or USDC). A session covers one currency on one chain.
Sign every request below with HMAC, as in Authentication. Send string values in JSON bodies so the signed text equals the sent text.

The flow

Step 1 — Generate a session key

Create a new secp256k1 key pair on the client. The address goes to the API. The private key never leaves the client.
python
Use a new key for every session. The API rejects an address that was used before, the zero address, and the addresses of your Safe and your owner wallet.

Step 2 — Prepare the delegation

Writes nothing. The server picks the cap, the expiry, and the nonce, and returns the typed data to sign.
The response is 200. The values below are illustrative:
Things to know about prepare:
  • Prepare does not reserve the nonce. If you prepare twice and register one result, the other then fails with session_nonce_invalid. Prepare again.
  • The cap, the expiry, and the nonce are the server’s choice. Do not change them.
  • The per-order cap is an environment setting. Read it from maxMakerAmount and do not hard-code it. The rolling budget and the price guard are not signed and are not in this response.

Step 3 — Sign the delegation with the owner wallet

Sign eip712 exactly as returned. This is the only time you need the owner key. In an interactive client, this is the wallet prompt.
python
Sign with the owner key, not the session key and not the Safe address. Do not edit the message. The API rebuilds the typed data from your create request, and the signature must match it.

Step 4 — Register the delegation

Register it soon after you prepare it.
The response is 201:
If you register past the limit of live sessions for your Safe, the oldest live session is revoked. Its orders stay on the book. To check a session later, or to find out if a stored key is still live:
It returns 200 with the object above, or 204 with no body when that key has no live session. chain_id is optional and defaults to the active chain.

Step 5 — Place orders signed by the session key

Order creation is unchanged. Follow Place an on-chain order: call signing-context, sign the eip712 it returns, and send POST /v2.0/orders/ with the same body. The one difference is the signer. Sign with the session key instead of the owner wallet. The snippet uses the helpers from the example script below.
python
Keep these in mind:
  • ownerAddress in the signing-context response is still your owner wallet. When a session key signs, you do not compare it with the signer.
  • The order nonce is one counter per Safe, shared with owner-signed orders. Run signing-context, sign, and create one after another.
  • An order keeps the expiry you signed. It stays on the book after the session expires or is revoked.
  • The order must stay inside the session’s limits. See the next step.

Handle rejections

When an order falls outside the session, POST /orders/ returns a 400 in the on-chain error format, with one of these codes: For the limit codes (session_scope_exceeded, session_price_guard, session_budget_exceeded), the session stays valid. Fetch a new signing context and sign the same order with the owner key. A rejected order does not use the session budget. For session_revoked and session_expired, discard the stored key and register a new session. You can fall back to the owner wallet meanwhile. The price guard compares your limit price with the best opposing price on the book. A resting order priced far from the market is rejected, in either direction. This also applies to a resting bid far below the best ask. The errors you can get while creating a session are listed in Errors.

Step 6 — Revoke the session

The response is 204 with no body. No wallet signature is needed. Revoking is idempotent. An unknown ID, or one that is not yours, returns 404. By default, revoking leaves the session’s resting orders on the book. Revoke when the user signs out, or when the key may be exposed. Delete the private key from the client at the same time.

Example script

This script registers a session key, places one order signed by the session key, falls back to the owner key if a session limit rejects it, and revokes the session. It repeats the HMAC and error helpers from End-to-end Python bot. It revokes with cancel_orders=1, so nothing rests on the book afterwards. In a real client, the owner signature in step 3 comes from the user’s wallet and not from a key in the script.
session_demo.py