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.LimitOrderIntent. For what a session key is and which limits apply, read Session keys first.
Prerequisites
Everything in Place an on-chain order, plus:- A registered, deployed Safe, with trading enabled for the currency.
- HMAC public and private keys for L2 request signing. See Get your API keys.
- The owner wallet, available once to sign the delegation.
- An on-chain currency (
OOMorUSDC). A session covers one currency on one chain.
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
Step 2 — Prepare the delegation
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
maxMakerAmountand 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
Signeip712 exactly as returned. This is the only time you need the owner key. In an interactive client, this is the wallet prompt.
python
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:
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 theeip712 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
ownerAddressin 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 withcancel_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