Skip to main content
Your Safe smart account holds the collateral you trade with. This page covers the endpoints that register it, report its state, relay its ERC-4337 UserOperations, and give the pool the standing allowance that bids need.
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.
The relay and enable-trading bodies contain a nested user_operation object. With HMAC, a nested value is signed as its Python repr, so sign these requests from Python or use a wallet session. See How values become text.

Register your Safe

Stores the address of your Safe for the active chain. The call is idempotent for the same address. It does not deploy anything. An HMAC API key cannot call this endpoint. It returns 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.
string
required
The address of the Safe owned by your wallet.
integer
Optional. Defaults to the active chain. Any other value is rejected.

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.
A rejected address returns 400 with attr: "safe_address" and one of these messages:

Response

Returns 200 OK with the Safe wallet object plus a migration object describing the legacy-balance migration check (it includes a reason).

Read your Safe

integer
Optional. Defaults to the active chain.
string
Send 1 to re-read the token balance from the chain instead of using the cached value.
Returns 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

string
The Safe address.
integer
Chain the Safe is on.
string
One of not_deployed, not_required, deploying, deployed, failed. Orders need deployed.
string | null
When deployment was confirmed.
string | null
Deployment transaction hash.
string | null
Last deployment error.
number | null
Last collateral balance read from the chain.
string | null
When last_balance was read.
string
Legacy-balance migration: none, pending, done, or failed.
string | null
Migration transaction hash.
string | null
When the migration finished.
string | null
Last migration error.
boolean
Whether real-money orders settle on-chain on this host.
boolean
Whether OOM orders settle on-chain on this host.
string
When the Safe was registered.
string
Last update.

Confirm deployment

Tells the API that your Safe now has code on-chain so it can update deploy_status. All fields are optional.
integer
Defaults to the active chain.
string
Hash of the deployment transaction.
string
Hash of the UserOperation that deployed the Safe.
Returns 200 OK with the Safe wallet object.

Trading status

Reports whether the pool has a standing allowance on your Safe for one currency.
string
default:"USDC"
USDC or OOM. Check each currency you trade.
integer
Defaults to the active chain.
boolean
true when the Safe is deployed and the allowance is at least half of the maximum uint256.
integer
Chain the status is for.
string
Currency the status is for.
string | null
Your Safe, or null if none is registered.
string | null
Your owner EOA.
string | null
The approve spender.
string | null
ERC-20 address of the currency. usdcToken carries the same value.
string
Current allowance in raw token units.
string
The amount to approve: the maximum uint256.
boolean
Whether the Safe is deployed.
string | null
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

Submits a signed ERC-4337 UserOperation in which your Safe calls 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.
object
required
A complete EntryPoint v0.7 UserOperation, signed by the Safe owner. The API checks that:
  • sender is your registered Safe,
  • signature is not empty,
  • callData is a Safe executeUserOp call that makes a plain, zero-value call to approve(pool, amount) on the token of currency.
Any other call is rejected. Approve approveAmountRaw from the trading status: enabled only turns true for an allowance of at least half the maximum uint256.
string
default:"USDC"
USDC or OOM. Must match the token the UserOperation approves.
integer
Defaults to the active chain.

Response

Returns 200 OK with the trading status fields plus:
boolean
true when the allowance was already in place. Nothing was submitted.
string | null
Hash of the submitted UserOperation, or null when alreadyEnabled is true.
string
When the allowance was confirmed. Present only when a UserOperation was submitted.
The request blocks while the API polls the allowance, for up to about 20 seconds.

Errors

Every failure returns 400 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.
Anything else returns 400 with the message This UserOperation is not allowed through the relay. If you send entry_point, it must be the EntryPoint in Environment.
object
required
The unsigned UserOperation. sender must be your registered Safe.
integer
Defaults to the active chain.
string
Optional. Must be the supported EntryPoint.
Returns 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

Takes the same body with the signed UserOperation. Returns:
Sample response (200 OK)

Read a receipt

Returns the bundler’s receipt, or {} while the UserOperation is not yet included. hash is accepted as an alias of user_operation_hash. chain_id is optional.

Bundler JSON-RPC

A JSON-RPC pass-through for smart-account client libraries.
string
required
One of pm_sponsorUserOperation, eth_sendUserOperation, eth_estimateUserOperationGas, eth_getUserOperationReceipt, pimlico_getUserOperationGasPrice. Other methods are rejected.
array
required
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.
integer
Defaults to the active chain.
Returns 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 move USDC out of your Safe, relay a UserOperation whose single call is transfer(to, amount) on the USDC token:
  1. Build the UserOperation with your Safe as sender.
  2. POST /me/safe/sponsor-user-operation/ and merge the paymaster fields.
  3. Sign it with the owner key.
  4. POST /me/safe/submit-user-operation/. Keep the returned userOperationHash.
  5. Poll GET /me/safe/user-operation-receipt/?user_operation_hash=... until the receipt is returned.
Rules:
  • USDC only. OOM cannot be withdrawn.
  • It is a plain, zero-value call to the USDC token with exactly transfer(to, amount).
  • to is not the zero address, the token itself, or the pool.
  • amount is 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. Through pimlico-rpc a withdrawal can be estimated and sponsored, but eth_sendUserOperation is refused.
A UserOperation that breaks a rule returns 400 with This UserOperation is not allowed through the relay.

Relay errors

Relay failures return 400 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.