IBEx Wallet

API

⛽ Bundler & Paymaster

IBEx.Fi implements the ERC-4337 (Account Abstraction) standard to enable gasless transactions. Users never need to hold ETH for gas — all operations are sponsored by the paymaster and bundled on-chain.

Infrastructure Stack

Architecture Overview

The Safe4337Pack from Safe's Relay Kit abstracts the bundler/paymaster interaction. All RPC calls (gas estimation, sponsorship, submission) are handled internally by the IBEx API — you only interact with the intent/execute endpoints.

The Intent / Execute Flow

Every on-chain operation follows a two-phase flow — intent (prepare) then execute (submit). This ensures the user confirms exactly what will happen before the operation is executed on-chain.

1 Intent: Client calls the intent endpoint (e.g. POST /v1.2/safes/operations/intent)
2 Gas estimation: Bundler estimates gas via eth_estimateUserOperationGas
3 Gas pricing: Bundler returns recommended gas prices
4 Sponsorship: Paymaster signs the UserOp via pm_sponsorUserOperation → returns paymasterAndData
5 Freeze: Gas values + paymasterAndData are frozen and stored in the SafeOperation (DB)
6 Client sign: User signs the UserOp hash with their passkey
7 Execute: Backend rebuilds the UserOp with frozen values + client signature, submits via eth_sendUserOperation
8 Re-sponsor safety net: If paymasterAndData expired, the backend re-sponsors before submission
Why freeze gas values? The paymaster signs the exact gas limits. If gas is re-estimated at execute time, the hash would change, invalidating the paymaster signature (error -32507). Freezing at intent time ensures consistency.

Bundler RPC Methods

Method Purpose When Used
eth_sendUserOperation Submit signed UserOp to the bundler for on-chain execution Execute phase
eth_estimateUserOperationGas Estimate callGasLimit, verificationGasLimit, preVerificationGas Intent phase
eth_getUserOperationReceipt Get the transaction hash and receipt for a submitted UserOp Cron / status check
eth_getUserOperationByHash Check if a UserOp was included in a bundle Cron / polling
pimlico_getUserOperationGasPrice Get recommended maxFeePerGas / maxPriorityFeePerGas Intent phase

Paymaster RPC Methods

Method Purpose When Used
pm_sponsorUserOperation Sponsor gas costs — returns signed paymasterAndData + updated gas limits Intent phase + re-sponsor safety net

Sponsorship Request Example

// pm_sponsorUserOperation call
{
    "jsonrpc": "2.0",
    "method": "pm_sponsorUserOperation",
    "params": [{
        "sender": "0x...",
        "nonce": "0x...",
        "initCode": "0x",
        "callData": "0x...",
        "callGasLimit": "0x...",
        "verificationGasLimit": "0x...",
        "preVerificationGas": "0x...",
        "maxFeePerGas": "0x...",
        "maxPriorityFeePerGas": "0x...",
        "paymasterAndData": "0x",
        "signature": "0x"
    }, "0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789"]
}

// Response
{
    "result": {
        "paymasterAndData": "0x...(signed payload)...",
        "callGasLimit": "0x...",
        "verificationGasLimit": "0x...",
        "preVerificationGas": "0x..."
    }
}

IBX Token Billing

While gas is sponsored (users never pay ETH), operations are billed in IBX tokens. After a UserOp is executed on-chain, the BillingService triggers an ERC-20 transfer of IBX from the user's Safe wallet to the billing destination address.

Sponsored Operations

The following on-chain operations are sponsored by the paymaster:

Operation Description
DEPLOY_WALLET First-time Safe deployment (initCode included in UserOp)
TRANSFER_TOKEN ERC-20 token transfers between wallets
SWAP_TOKEN Token swaps via CoW Swap / 1inch
ENABLE_RECOVERY Setting up a recovery module on the Safe
POOL_DEPOSIT Depositing tokens into AAVE lending pools
POOL_WITHDRAW Withdrawing tokens from AAVE lending pools

Error Handling

Error Code Meaning Resolution
AA31 Paymaster deposit too low — the paymaster contract doesn't have enough ETH staked in the EntryPoint Fund the paymaster contract (infrastructure)
AA33 Operation gas cost exceeds paymaster limit — gas estimation at intent time was too high Retry the operation (new intent with fresh gas values)
-32507 Invalid paymaster signature — gas values changed between sponsor and execute Re-sponsorship safety net auto-handles this

See the full error reference for all AA error codes, JSON-RPC errors, and Safe-specific errors with detailed resolution strategies.

Solana: Fee Payer

Solana doesn't use ERC-4337. Instead, IBEx implements a fee payer model: the transaction is built unsigned by the client, the server adds a fee payer signature (the server pays the SOL fees), and returns the co-signed transaction for the client to submit. 

// Solana fee payer flow
1. Client builds transaction (unsigned)
2. POST ${WEB3_URL}/${chainId}/rpc/sign-transaction
   → Server signs as fee payer
3. Client receives co-signed transaction
4. Client submits via sendRawTransaction
Chain IDs: Solana Mainnet = 900, Solana Devnet = 901

← Back to Documentation