Session keys are coming soon. They are not available on
https://api.futuur.com, where settlement is still HMAC-only and ledger-based. This page explains the model so you can prepare. The endpoints are documented only in the developer guide, and they are not live on https://api.futuur.com.Why session keys exist
Every Web3 order needs an EIP-712LimitOrderIntent signed by the Safe owner wallet. See On-chain trading. In a browser or mobile wallet, that means a wallet prompt on every order.
A session key removes the prompt. You sign one SessionDelegation with the owner wallet. It names the session key and the limits it works within. From then on, the Futuur backend accepts LimitOrderIntent signatures from that key.
How it works
- The client generates a new key pair. The private key stays with the client.
- The owner wallet signs one
SessionDelegationnaming the session key’s address. This is the only wallet prompt. - The backend checks that the owner signed it and stores it.
- For each order, the client signs the usual
LimitOrderIntentwith the session key instead of the owner wallet. - The backend recovers the signer. If it is the owner, the order takes the normal path. If it is a live session key of that Safe, the backend first checks the session limits.
POST /orders/ body, with the signature coming from the session key.
Verification happens off-chain, in the Futuur backend. No on-chain registry is involved, and a session key costs no gas.
What a session key can do
- Sign
LimitOrderIntentfor any market, buys and sells. - Work for one currency on one chain. The delegation names both.
- Last for a fixed period, about 30 days at the time of writing. The
expiryfield on the session is authoritative.
What a session key cannot do
- Withdraw funds from your Safe.
- Change the owners of your Safe.
- Trade a currency or chain other than the one it was created for.
- Place an order outside its limits.
- Outlive its
expiry.
Lifetime and renewal
A session lasts until itsexpiry, or until you revoke it. Futuur chooses the expiry when you prepare the delegation. You cannot extend a session.
To renew, create a new session with a new key before the old one expires. You can have several live sessions at once, so the old one keeps working until its expiry or until you revoke it. A session key address can be used for one session only. After a session ends, generate a fresh key.
When a session expires or is revoked, orders it already placed stay on the book. Only new orders it signs are rejected.
Limits
Three limits apply to orders signed by a session key. Orders signed by the owner wallet are never subject to them.
The limit values are environment settings. They can differ between environments and can change. The response from
prepare reports the per-order cap as maxMakerAmount, in raw token units. Divide it by 10 ^ decimals to get currency units. Futuur can later lower a limit for sessions that are already live.
An order outside a limit is rejected with one of the codes below. The session stays valid. Sign that order with the owner wallet instead.
Session error codes
POST /orders/ returns these as a 400 in the on-chain error format. The backend checks them in this order and returns the first that fails.
A rejected order does not count against the budget. For the full list, including codes returned while you create a session, see Errors.
Revoking a session
You can revoke a session at any time. Revoking needs your authenticated API access and no wallet signature, because it only removes power.- By default, revoking leaves the orders the session placed on the book. They keep the expiry they were signed with.
- To cancel the session’s open orders as well, revoke with
cancel_ordersset. Use this when a key may be exposed. - Revoking twice is safe.
Several sessions per Safe
Each browser or device can hold its own session. A Safe can have several live sessions at once. When you register a session past the limit, the backend revokes the oldest live sessions. It leaves their orders on the book.Security notes
- Keep the private key secret. Do not log it, commit it, or send it to any server, including Futuur’s. Futuur never needs it. It only sees the signatures.
- It only trades. A session key cannot withdraw or change Safe owners. Worst case, it places orders inside the per-order cap, the rolling budget, and the price guard.
- It needs more than the key. To place an order, the client also needs authenticated API access to your account.
- Revoke it if you think it leaked. Revoke with
cancel_ordersset, then register a new session with a new key. - Store it encrypted. If your client keeps the key between runs, encrypt it at rest. Delete it when the user signs out.
- One key per client. Do not share a session key between devices.
How the Futuur website uses session keys
On the Futuur website, this will be automatic, with no extra screens:- The first Web3 bet asks your wallet for one signature. That is the delegation.
- Later bets are signed in the browser with the session key. Your wallet is not involved.
- The browser keeps the key encrypted in browser storage.
- When the session is close to expiry, the next bet creates a new session.
- If you decline the signature, or an order is rejected by a limit, that bet is signed by your wallet instead.
- When you log out, the browser deletes the key and revokes the session. Your resting orders stay on the book.
Who should use session keys
Use them when the owner wallet is interactive and a person must approve each signature: a browser wallet, a hardware wallet, or a mobile wallet. If you trade through the API and already sign each order with your own key, a session key gains you nothing. Your program already holds the owner key, and it needs that key to sign the delegation anyway.Related
- Session keys for developers: the request flow, step by step
- On-chain trading: matching, settlement, and the two layers of auth
- Place an on-chain order: signing a
LimitOrderIntentwith the owner wallet - Errors: every session error code