How Karwan works
Karwan secures USDC in escrow while a service is delivered. There are two ways to open a deal, one settlement spine underneath. This is the walkthrough: the flows, the on-chain calls, and the Circle products behind them. Every step is a real transaction on Arc Testnet.
When you already have a counterparty
You agreed with someone off-platform. Karwan just secures the money while the work gets done.
On /buyer, pick "I have a seller". Enter their wallet address, the amount, a deadline, and how much releases on delivery. The escrow funds on Arc, naming that seller directly.
The seller signs in with the wallet you named. The deal is waiting on their dashboard. When the work is done, they mark it delivered, which unlocks your releases.
You release the first slice, then verify the work and release the rest. The escrow settles, the platform fee is collected, and the seller's reputation is recorded on chain.
When you need an agent to find one
Post a brief and the agents run the auction and negotiation for you.
On /buyer, pick "Find me a seller". Write what you need, set a budget and deadline. A postJob transaction lands on Arc in a few seconds.
The seller agent scores the brief and calls submitBid. Your buyer agent ranks it, counters once, and accepts the best terms. Each step shows on the live timeline.
On acceptance, the buyer agent approves USDC and funds the escrow. When the work is done, release the milestones. Funds move to the seller in tranches.
The on-chain calls
A managed deal walks the full path below. A direct deal skips straight to fundEscrow, naming the seller without an auction.
postJob(bytes32, uint256, uint64, string)
Buyer agent · managed only
Records the brief on the JobBoard. Emits JobPosted, the event seller agents subscribe to.
submitBid · counterOffer · respondToCounter · acceptBid
Both agents · managed only
The negotiation loop. Seller bids, buyer counters once, seller responds, buyer locks final terms.
USDC.approve(escrow, fundedAmount)
Buyer agent
ERC-20 approval so KarwanEscrow can pull funds. The approval covers the deal amount plus the buyer's half of the platform fee.
fundEscrow(bytes32, address, uint256, uint8[])
Buyer agent
Locks the deal amount with a milestone schedule. The contract pulls dealAmount + feeHalf, stores what the seller nets and what the treasury collects. Emits EscrowFunded.
releaseProgress(bytes32, uint8)
Buyer
Releases one milestone. The seller gets their cut, the treasury gets its proportional slice of the 1.5% fee. The final milestone sweeps any remainder and marks the escrow settled.
recordCompletion(bytes32, address, address, uint8)
Buyer agent
On settlement, records the outcome against the seller on KarwanReputation. ERC-8004 forbids self-rating, so the buyer rates the seller.
The reputation engine, end to end
Every wallet has a composite score in [0, 1000] derived from completed deals, locked stake, time on the platform, and a spam-detection penalty. The score binds to one of five tiers and gates how aggressively the agent loop negotiates on your behalf.
On /profile · STAKE, deposit any amount into KarwanVault. No forced lock, no minimum tenure. The longer it sits, the more weight it carries in the formula.
NEW · COLD · ESTABLISHED · STRONG · ELITE. Each tier unlocks specific agent behavior. ELITE sellers skip the auction; NEW buyers pay a premium that surfaces to the seller for human review before approval.
Request a withdrawal, the position enters a 7-day cool-down while fraud checks run. Cancel inside the window to resume without losing tenure. After cool-down, claim returns principal in a single transaction.
What we use, and where
USDC
The currency we settle in. Holds deal amounts, escrow balances, milestone payouts, the platform fee, and KarwanVault staking principal.
Developer-Controlled Wallets
Every agent runs on an SCA wallet on Arc Testnet. The buyer agent funds escrows and releases milestones; the seller agent bids and negotiates. Identity DCWs sign vault deposits and withdrawals for Circle-auth users with no wallet popup.
CCTP V2
Buyer USDC bridges in from Base or Ethereum Sepolia. The user signs the burn, the backend relays the mint on Arc once Circle attests.
Arc Testnet
Chain 5042002. Blocks finalize in under a second. USDC is the native gas token, and the ERC-8004 identity registry is already deployed here.
Resend
Transactional email for OTP sign-in and deal alerts. Inline brand logo via CID. Falls back to a dev-only autofill when keys are unset so local builds keep working.
Hashnote USYC (mainnet)
On mainnet KarwanVault routes idle stake through USYC for roughly 5% APY. Reputation signal is unchanged so the same dollars earn yield + tier lift. Testnet holds plain USDC.
Coming next
What ships after the testnet build.
Bring your own agent
Institutional customers register their own agent address per ERC-8004 with a custom policy file. Zero contract changes; the same buyer / seller flow runs against a customer-controlled worker.
Sharded multi-tenant
Per-user partition keys, Redis Streams for chain-event fan-out, N stateless workers behind. Same contracts, same SSE shape, parallel throughput for Circle + LLM rate limits.
Disputes and appeals
On-chain dispute resolution, plus a seller appeal path to renegotiate if a buyer stalls on release.
Mainnet USYC routing
KarwanVault forks with a USYC adapter. Stake compounds in tokenized T-bills while it builds reputation. Treasury fees route the same path so platform revenue earns yield.
Common questions
What is the difference between a direct deal and a managed deal?+
A direct deal is for two parties who already found each other. You open an escrow naming the seller's wallet, no auction. A managed deal is for when you need a seller: you post a brief and agents run the auction and negotiation. Both use the same escrow, reputation, and settlement underneath.
What is the platform fee?+
1.5% of the deal amount, split evenly between buyer and seller. The buyer funds the deal amount plus their half; the seller nets the deal amount minus their half. The fee is collected on chain by the escrow contract as milestones release, and goes to a treasury address.
Who controls the agent wallets today?+
For this demo, agent wallets are Circle Dev-Controlled Wallets we provisioned ahead of time. In v1, each user connects their own wallet and either activates an agent under a spending allowance they set, or runs their own.
Are the smart contracts deployed?+
Yes. KarwanJobBoard, KarwanEscrow, and KarwanReputation are live on Arc Testnet (chain 5042002). The escrow carries the platform fee split on chain. Every event on the Activity feed links to its transaction on testnet.arcscan.app.
How is escrow released?+
The buyer releases each milestone with releaseProgress. The seller's cut goes to the seller, the treasury's slice of the fee goes to the treasury, and the final release marks the escrow settled. In a direct deal the seller must mark the work delivered before the buyer can release. Disputes today go to manual review; v1 adds on-chain arbitration.
What if the seller agent skips my managed job?+
The seller's profile has a budget and deadline range. If your brief falls outside it, the agent skips and the timeline shows you why. The LLM can also skip on confidence, and that gets logged too.
Why this corridor?+
We started with MEASA because UAE non-oil trade with Africa alone is $50B+ and growing about 15% a year, with heavy informal volume and weak card rails. But the escrow, reputation, and agent layer is corridor-agnostic. It works for any cross-border service deal.
Where does the LLM run?+
Agent decisions go through OpenRouter (default model: google/gemini-2.5-flash-lite) to keep cost low. We use Zod schemas for structured outputs, so an agent can only act inside its accepted budget and deadline range.
Try it on Arc Testnet
The dashboard runs both flows against real testnet contracts.
chain 5042002 · testnet.arcscan.app