These endpoints are part of phase one and run on the preview host only. See Environment for the chain and addresses. They are not live on
https://api.futuur.com.
Withdrawing USDC uses the relay endpoints and is not available to API keys.
Authentication
All endpoints require authentication.
POST /me/safe/ only accepts a wallet sign-in session. The others also accept HMAC headers (Key, Timestamp, HMAC). See the authentication guide.Register your Safe
403 with code permission_denied and detail This action is not available to API keys. Register the Safe while signed in with your wallet. The Futuur web app does this for you on first sign-in.
Rules
The address is accepted only when all of these hold:- Your account has a
wallet_address. That EOA is the Safe owner. - The address is not your owner EOA itself.
- You have no Safe registered yet, or you are sending the same address again. A registered Safe cannot be changed.
- The address is not registered to another account.
- If a contract already exists at the address, it is a 1-of-1 Safe whose only owner is your
wallet_address. A Safe that is not deployed yet is accepted as a predicted address and checked the same way once it has code.
400 with attr: "safe_address" and one of these messages:
Response
Returns200 OK with the Safe wallet object plus a migration object describing the legacy-balance migration check (it includes a reason).
Read your Safe
200 OK with the Safe wallet object. If you have no Safe on that chain it returns 404 with this body:
404 Not Found
Safe wallet object
Confirm deployment
deploy_status. All fields are optional.
Returns 200 OK with the Safe wallet object.
Trading status
A reason when trading is not enabled, for example
No Safe registered for this chain. or Safe is not deployed on-chain yet.Sample response (200 OK)
Enable trading
approve(poolAddress, amount) on the collateral token, then waits until the allowance is visible on-chain. Do this once per currency. After it succeeds, bids need no per-order approval.
A complete EntryPoint v0.7 UserOperation, signed by the Safe owner. The API checks that:
senderis your registered Safe,signatureis not empty,callDatais a SafeexecuteUserOpcall that makes a plain, zero-value call toapprove(pool, amount)on the token ofcurrency.
approveAmountRaw from the trading status: enabled only turns true for an allowance of at least half the maximum uint256.Response
Returns200 OK with the trading status fields plus:
The request blocks while the API polls the allowance, for up to about 20 seconds.
Errors
Every failure returns400 in the two-entry form with code trading_not_enabled. Read the message:
Relay
The API relays UserOperations for your Safe to its bundler and paymaster so you do not need your own. The relay accepts only these operations from your registered Safe:- the deploy operation: a zero-value call from the Safe to itself with empty data,
approve(pool, amount)on a collateral token, and- a USDC withdrawal,
transfer(to, amount), for wallet sign-in sessions only. See Withdraw from the Safe.
400 with the message This UserOperation is not allowed through the relay. If you send entry_point, it must be the EntryPoint in Environment.
Sponsor a UserOperation
200 OK with the paymaster’s pm_sponsorUserOperation result, unchanged. Merge those fields into the UserOperation, then sign it with the owner key.
Submit a UserOperation
Sample response (200 OK)
Read a receipt
{} while the UserOperation is not yet included. hash is accepted as an alias of user_operation_hash. chain_id is optional.
Bundler JSON-RPC
One of
pm_sponsorUserOperation, eth_sendUserOperation, eth_estimateUserOperationGas, eth_getUserOperationReceipt, pimlico_getUserOperationGasPrice. Other methods are rejected.The JSON-RPC parameters. For the first three methods,
params[0] is the UserOperation (same restrictions as above) and params[1] must be the supported EntryPoint.200 OK with {"result": ...}. A bundler error is also a 200, shaped {"error": {"message": "...", "code": ..., "data": ...}}. A request the relay refuses is a 400.
Withdraw from the Safe
To moveUSDC out of your Safe, relay a UserOperation whose single call is transfer(to, amount) on the USDC token:
- Build the UserOperation with your Safe as
sender. POST /me/safe/sponsor-user-operation/and merge the paymaster fields.- Sign it with the owner key.
POST /me/safe/submit-user-operation/. Keep the returneduserOperationHash.- Poll
GET /me/safe/user-operation-receipt/?user_operation_hash=...until the receipt is returned.
USDConly.OOMcannot be withdrawn.- It is a plain, zero-value call to the USDC token with exactly
transfer(to, amount). tois not the zero address, the token itself, or the pool.amountis greater than zero, in raw units (6 decimals).- You are signed in with your wallet. A request authenticated with an HMAC API key is refused.
- It is sent with
submit-user-operation. Throughpimlico-rpca withdrawal can be estimated and sponsored, buteth_sendUserOperationis refused.
400 with This UserOperation is not allowed through the relay.
Relay errors
Relay failures return400 with the message in the entry whose attr is detail. When the bundler rejected the call, further entries whose attr starts with pimlico carry its error data.
Related
- Environment — chain, token, pool, and EntryPoint addresses
- Place an on-chain order — where these calls fit
- Errors — error format and codes