Guaranteed-price swaps with bonded solvers
FirmSwap is a firm-quote swap protocol where solvers commit to exact prices bound to an on-chain deadline. No slippage, no MEV, and if the solver misses the deadline — full refund plus bond compensation.
Why FirmSwap Exists
FirmSwap was born from a real problem at Picnic, a fully on-chain crypto neobank for Brazilian users. Picnic trades BRLA, a Brazilian Real stablecoin, to and from USDC — enabling users to go from fiat to any token in seconds via DeFi.
The Problem
Picnic, a fully on-chain crypto neobank for Brazilian users, needed predictable FX swaps. Users would sign a swap transaction before paying via PIX, but the PIX-to-BRLA pipeline takes time — the user goes to their bank, pays PIX, and the payment becomes on-chain BRLA. By the time tokens arrived, the price had moved. An extra approval transaction made UX even worse.
The Gap
In traditional finance, services like Wise guarantee a quoted exchange rate for hours — sometimes even days. In DeFi, prices expire in seconds. Users were shown one price at quote time and received another at execution. This created frustration and eroded trust in a system that should be more transparent, not less.
The Solution
FirmSwap locks every quote to an exact price and an on-chain deadline. Solvers bond capital as collateral — if they miss the deadline, users get a full refund plus bond compensation. Zero-transaction deposits remove the extra approval step. No slippage, no surprises, no trust assumptions.
That's crypto solving real-world problems.
How It Works
Three steps from quote to settlement. Every quote is locked to an exact price and an on-chain deadline. Miss the deadline, and the protocol compensates the user automatically.
Request a Quote
User requests a swap quote. The API fans out to all registered solvers and returns the best firm quote — locked to exact amounts and a deadline — signed with EIP-712.
Deposit Tokens
Deposit before the deposit deadline. Two modes: (A) Transfer tokens to a deterministic CREATE2 address — zero user transactions. (B) Call deposit() on the contract.
Solver Fills
The solver delivers exact output tokens before the fill deadline. If the deadline passes without delivery, the user calls refund() and receives their tokens back plus 5% of the solver's bond.
Architecture
A permissionless system where anyone can run the API, any solver can register with a bond, and users interact through the SDK or directly with the contract.
User sends tokens to a deterministic CREATE2 address. settle() sweeps funds and completes the swap in one transaction. Zero user transactions with the contract.
User calls deposit() with the solver-signed quote. Solver calls fill() to deliver output tokens. Two transactions total. Permit2 supported.
How FirmSwap Compares
FirmSwap is the simplest bonded-solver protocol. No token, no DAO, no oracle — just guaranteed prices with deadline enforcement and accountability.
| Feature | FirmSwap | CoW Protocol | UniswapX | 1inch Fusion | Across |
|---|---|---|---|---|---|
| Price guarantee | Firm (exact) | Batch auction | Dutch auction | Dutch auction | Firm |
| Deadline model | On-chain (uint32) | Batch window | Auction decay | Auction decay | On-chain |
| Solver bond | 5% per order | No | No | No | Yes |
| Contract size | ~630 lines | ~5,000+ | ~3,000+ | Closed source | ~4,000+ |
| Governance | None | CowDAO | Uniswap DAO | 1inch DAO | UMA DAO |
| Token required | None | COW | UNI | 1INCH | ACX |
| Oracle dependency | None | Batch auction | None | None | UMA oracle |
| Zero-tx deposit | ✓ | ✗ | ✗ | ✗ | ✗ |
| ERC-7683 | ✓ | ✗ | ✗ | ✗ | ✗ |
Run a Solver
Earn spread profits by providing firm quotes with on-chain deadlines. Bond 1,000+ USDC, register with any API instance, and start quoting. Each quote you sign commits to an exact price and a fill deadline — your obligation expires if the user misses the deposit window. The reference solver includes a pluggable CEX adapter system.
- ✓Permissionless registration — just post a bond
- ✓Configurable spread (default 0.5%)
- ✓Deadline-bound quotes — your commitment has a clear expiry
- ✓Auto-fill deposits with on-chain monitoring
- ✓Open source reference implementation
# Clone and configure
$ git clone https://github.com/purybr365/firmswap.git
$ cd firmswap/solver
$ cp .env.example .env
# Set SOLVER_PRIVATE_KEY, CHAIN_ID, RPC_URL
# Install and start
$ npm install
$ npm start
> Solver registered on chain 100
> Listening on http://0.0.0.0:3001
> Monitoring for deposits...import { FirmSwapClient } from "@firmswap/sdk";
const client = new FirmSwapClient({
apiUrl: "https://api.firmswap.org",
chainId: 100,
});
const quote = await client.getQuote({
inputToken: BRLA,
outputToken: USDC,
orderType: "EXACT_INPUT",
amount: "1000000000000000000",
userAddress: "0x...",
depositMode: "ADDRESS",
});
// Zero-tx deposit — just transfer tokens
const addr = await client.getDepositAddress(quote);Integrate FirmSwap
Add guaranteed-price swaps with deadline enforcement to your dApp in minutes. Every quote includes deposit and fill deadlines — the user knows exactly when their trade expires. Built on viem with full type safety, ERC-4337 support, and Permit2.
- ✓TypeScript SDK with full type safety
- ✓Smart account / ERC-4337 batching support
- ✓Built-in safety checks (address verification, quote validation)
- ✓Configurable deadlines — set deposit and fill windows per quote
- ✓WebSocket for real-time order updates
Security by Simplicity
No token. No DAO. No oracle dependencies. FirmSwap's security comes from its simplicity — fewer moving parts means fewer attack vectors.
No Governance
Zero governance means zero governance attacks. No admin keys, no proxy upgrades, no emergency functions. The contract is immutable — it does exactly what it does today, forever.
Bonded Solvers
Every solver bonds USDC on-chain. 5% is reserved per active order. Each quote has an on-chain fill deadline — if the solver misses it, their bond is slashed and the user receives compensation. 7-day unstake delay prevents hit-and-run attacks.
Security-First Design
Internal review completed with 20 findings remediated across all severity levels. External audit planned before mainnet. EIP-712 typed signatures and ReentrancyGuard on all state-mutating functions.
Roadmap
From smart contracts to cross-chain settlement — built incrementally, tested thoroughly.
Smart Contracts
Done630 lines of immutable Solidity. EIP-712 typed signatures, Permit2 support, CREATE2 address deposits, ERC-7683 compatible.
API + Solver + SDK
DoneMulti-chain quote aggregator API, reference solver with CEX price integration, TypeScript SDK built on viem.
Testnet Deployment
DoneLive on Gnosis Chiado testnet. Full end-to-end flows verified: both deposit modes, refunds, bond slashing.
Security Audit
PlannedInternal security review completed with 20 findings remediated (3 critical, 8 high, 7 medium, 2 low). External audit planned before mainnet.
Mainnet Launch
PlannedGnosis Chain mainnet deployment with production solver infrastructure and monitoring.
Multi-chain Expansion
PlannedDeploy to Base, Polygon, Arbitrum, and Optimism. Single API instance serving all chains.
Cross-chain Support
FutureFill orders on a different chain than the deposit chain. Full cross-chain intent settlement.