FirmSwap Documentation

FirmSwap is a firm-quote swap protocol with bonded solvers. Solvers commit to exact prices before users deposit tokens. If a solver fails to deliver, the user gets a full refund plus 5% of the solver's bond as compensation.

Key Concepts

Firm Quotes

Unlike AMMs or Dutch auctions, FirmSwap quotes are binding and time-bound. When a solver signs a quote with EIP-712, they commit to delivering exactly the quoted output amount before an on-chain fill deadline. There is no slippage, no price impact, and no MEV extraction. If the solver misses the deadline, the user gets a full refund plus bond compensation.

Bonded Solvers

Every solver must bond USDC on-chain before they can quote. For each active order, 5% of the output value is reserved from the solver's bond. If the solver defaults, this amount is slashed and given to the user as compensation.

Two Deposit Modes

• Address Deposit (Mode A): A deterministic CREATE2 address is computed for each quote. The user transfers tokens to this address using any method (wallet, CEX withdrawal, etc.). The solver calls settle() to complete the swap. Zero user transactions with the contract.
• Contract Deposit (Mode B): The user calls deposit() on the FirmSwap contract. The solver calls fill() to deliver output tokens. Permit2 is supported for gasless approvals.

Deadlines

Every quote includes two on-chain deadlines:

• Deposit Deadline (depositDeadline): The user must deposit tokens before this Unix timestamp. Deposits after this time are rejected by the contract. Default: 5 minutes from quote creation.
• Fill Deadline (fillDeadline): The solver must deliver output tokens before this timestamp. If the deadline passes without a fill, the user can call refund() to reclaim tokens and slash the solver's bond. Default: 2 minutes after the deposit deadline.

Both deadlines are part of the EIP-712 signed struct — they cannot be modified after the solver signs the quote. The user can request a custom deposit window via the depositWindow parameter in the quote request.

No Governance

FirmSwap has no owner, no admin keys, no proxy upgrade pattern, and no governance token. The contract parameters (5% bond, 1,000 USDC minimum, 7-day unstake delay) are immutable constants. This is a deliberate design choice — the protocol's simplicity is its security.

Who Is This For?

Integrators

Add guaranteed-price swaps to your dApp using the TypeScript SDK. The SDK handles quote fetching, deposit construction, and safety checks. See the Quick Start to get started.

Solvers

Earn spread profits by providing firm quotes. The Solver Guide covers how to run the reference solver, configure CEX adapters, and register with an API instance.

Protocol Developers

Understand the smart contract architecture, bond mechanics, and EIP-712 signing scheme in the Smart Contracts and Architecture docs.

Testnet

FirmSwap is live on Gnosis Chiado testnet: