Everything users need to understand Splitsy.

Splitsy is built for groups that need more than a calculator screenshot. A splitter can upload a receipt, review the extracted bill, assign payer wallets, and create an onchain record of each participant's share. Payers can connect their wallets later, see only their own debts, pay in full or partially, and bridge USDC into Arc when their balance lives on another supported testnet.

The application has two product surfaces. Bills are one-time debts linked to a receipt or expense.Recurring tabs are scheduled payment agreements, such as rent, subscriptions, shared services, or repeating household costs. Both flows are designed around explicit wallet approval and visible balances.

Splitsy lets you split a bill with anyone by their handle or email — even before they have ever opened the app. You sign in with X, Discord, Google, or a one-time email code, and each method gives you a ready-to-use USDC wallet on Arc Testnet, so a debtor never has to install a browser wallet, hold a seed phrase, or understand gas to pay what they owe. This section explains exactly what data is used, how the wallet is created, and why Splitsy makes the choices it does.

How the identity flow works

Why a developer-controlled wallet (and not a user-controlled one)

Circle offers two wallet models. A user-controlled walletis non-custodial but requires the user to authenticate to Circle directly — via Google, Apple, Facebook, email OTP, or a PIN — because the user holds a key share. Some of Splitsy's sign-in methods (like X and Discord) are not supported Circle logins at all, so they cannot unlock a user-controlled wallet; and for the ones that overlap, bridging the two would still force every debtor through a second, unrelated login (and a recovery-phrase burden) just to pay a dinner split — the exact friction Splitsy exists to remove.

A developer-controlled wallet is created and operated server-side, keyed to a reference id (your provider identity). That lets Splitsy give anyone a working USDC wallet the instant they sign in — under a single, uniform model across all four providers, with no extra login, no seed phrase, and no app to install. Because Splitsy runs on Arc Testnet with test USDC that has no monetary value, the custodial trade-off carries no financial risk while delivering the smoothest possible onboarding. A future mainnet deployment would revisit this and offer genuine self-custody for real funds.

Off-chain ledger for handle-tagged bills

The BillSplitRegistrycontract records debts by wallet address and needs every participant's address at creation time. A handle or email you tag may belong to someone who has not signed in yet and therefore has no address, so tagged bills are not written to the registry. Instead they live in an off-chain ledger: the bill and each debtor's share are stored keyed by provider + handle/email, and are linked to a real wallet the moment that person signs in. This is a deliberate second mode alongside the on-chain registry, chosen so you can split with anyone without knowing their address.

The one-time bill flow is anchored by BillSplitRegistry. The registry does not need to know the full receipt body; it stores a hash of bill metadata plus the participant list and amounts. This keeps the contract focused on debt accounting while leaving rich receipt display to the app.

Amounts are represented with 6 decimals to match USDC. User-entered dollar values are converted into USDC base units before they are submitted to the contract.

Every on-chain bill carries a verification badge in the payer's view. It answers two different questions, and the whole design hinges on keeping them separate:

What actually goes on-chain

Storing a full receipt on a blockchain would be expensive and public. Instead, only a 32-byte fingerprint is committed. When a bill is created, Splitsy computes a keccak256 hash over the bill's canonical fields and passes it to createBill(bytes32 metadataHash, address[] participants, uint256[] amounts). The contract emits BillCreated with that hash; it can never be edited afterward.

metadataHash = keccak256(
  abi.encode(
    merchant,           // string,   e.g. "ROYAL HANDI HUT"
    currency,           // string,   e.g. "USD"
    cents,              // uint256,  total in cents (e.g. 300 = $3.00)
    labels.join("|"),   // string,   participant labels in order
    receiptHash,        // string,   keccak256 of the receipt image ("" if none)
    dueDate             // uint256,  optional "pay by" Unix seconds — appended
  )                     //           ONLY when the creator set a deadline
)

The optional dueDate is a strictly additive commitment: a bill with no deadline encodes exactly as bills did before due dates existed, so every previously created bill still verifies byte-for-byte. When present, it anchors the deadline that payment reputation grades timeliness against — the creator cannot move it after the fact.

All-or-nothing bills

A bill with a due date can also be created all or nothing (escrowUntilFull). On a normal bill each payment is the creator's the moment it lands — they can claim it straight away. Tick the box and nothing is claimable until everypayer has settled. Use it when a partial amount is no good to you: six concert tickets, a group gift, a deposit. $160 does not buy six $40 tickets, and holding four people's money for a purchase that isn't happening helps nobody.

That is also why an all-or-nothing bill must have a due date; the registry rejects the pair at creation otherwise. Without a deadline there is no moment at which a short bill counts as failed, so in a contract with no owner, no pause and no sweep the money could never be released to anyone. With one, every route out is self-service: pay it off and the creator claims, or miss it and the payers withdraw.

A refund puts that payer's share back on the board rather than killing the bill, so a late payer — or an autopay agent calling payDebtFor — can still complete it afterwards, and the creator can still be paid in full. collectDebtalso still unlocks at the deadline on these bills, because pulling from debtors who granted a mandate is exactly what can carry a short bill over the line. Anything pulled that doesn't is refundable to the debtor it came from, so the mandate cannot be used to extract money from a failed bill.

The human-readable values behind that hash — the preimage— are published off-chain to Supabase so a payer's browser can recompute the hash and compare. The preimage is only a convenience transport: it is never trusted. The server that stores it first reads the real metadataHashback from Arc and refuses to save any preimage that doesn't hash to it, so a stored record is always genuine.

The receipt image is committed too

To make check 2 possible, the receipt itself is bound to the bill. In the creator's browser the photo is downscaled and re-encoded to a compact JPEG (~80 KB), then hashed with keccak256. That receiptHash is one of the fields inside metadataHash above, so the exact image is anchored on-chain. The image bytes themselves are uploaded to a public Supabase Storage bucket keyed by registry/billId. The publish route re-hashes the uploaded bytes and rejects anything that doesn't match the committed receiptHash, so the stored image is provably the committed one. Bills typed in by hand have no image and commit receiptHash = "".

What the payer's browser does

Verification runs entirely in the payer's browser and trusts only the chain — Supabase is just a delivery pipe. The two checks map directly to the two badge lines:

What each badge state means

Every payer who settles an on-chain bill in full earns verifiable payment reputation using the ERC-8004registries Arc pre-deploys on testnet — no Splitsy contract is involved. The payer's wallet receives an identity NFT on the IdentityRegistry, and each completed payment is recorded as a scored feedback entry on the ReputationRegistry. When someone later tags that payer into a new bill, the creation form shows a badge: "Paid N bills in full on Arc · 97/100 timeliness".

How a score is earned

The scoring curve

Paying is always positive — even a very late payment is evidence of good faith, so the floor is a passing 50, and a payment that is never made simply records nothing. The badge's aggregate is an amount-weighted average: each payment is weighted by the payer's USDC share, so a large bill paid late drags the average more than a small one. Weighting happens only at aggregation; every on-chain score stays simple and independently verifiable. Recurring tabs score too: each settled cycle a member is collected from earns one independent score, graded against that cycle's boundary.

Three wallets, by design

ERC-8004 forbids an agent's owner from scoring its own agent, so Splitsy separates roles across three distinct wallets:

Verify a score yourself

Every feedback entry commits feedbackHash = keccak256("splitsy:bill:<billId>:<payTxHash>") (recurring cycles use splitsy:tab:<tabId>:cycle:<n>:<settleTxHash>), and its fileuri field carries the same payment hash as tx:<payTxHash>. That makes each score independently re-checkable against the payment it claims to describe, with nothing but a block explorer:

What the badge shows — and what it never does

• The badge appears while tagging payers into a new bill, looked up by handle, email, or address.
• It shows the count of bills paid in full, the amount-weighted timeliness average, and how many were late.
• Looking up a handle never reveals the wallet address behind it — the API returns only the aggregate.
• Looking up a handle never creates a wallet; wallets are only provisioned when a bill is actually created.
• "No payment history yet" covers both "person unknown" and "wallet known, no payments" — deliberately indistinguishable.

Optionally, each identity NFT's metadataURI points to an agent profile pinned to IPFS (name, agent type, wallet). Without IPFS configured, registration falls back to an inline data: URI — the reputation mechanics are identical either way.

Recurring tabs are fixed-share payment schedules. A creator chooses a recipient, interval, maximum number of settlement cycles, member wallets, and each member's fixed USDC share. Members approve the tab contract as a constrained USDC spender. Funds remain in member wallets until settlement runs.

The debtor view shows approved amount, wallet balance, paid total, total debt, cycles due, and progress. A paid tab uses a paid-bill stamp. The splitter view shows every member's share, due amount, remaining total, wallet balance, allowance, and collected total.

Splitsy uses Circle and Arc technology for USDC movement and settlement. Arc Testnet is the destination network for the app's contracts. Circle Gateway enables cross-chain USDC payments from any supported source chain directly to Arc Testnet in one flow.

When someone raises a bill against you, you can have it settled without opening the app. The thing that settles it is your own agent: a wallet on Arc that belongs to your Splitsy account, holds its own USDC balance, carries its own ERC-8004 identity NFT, and spends strictly under ceilings you set. It draws only on what you have sent it — Splitsy takes no allowance on your own wallet to make this work.

Funding your agent

The Fundbutton sits next to the agent's balance on the settlement-agents panel. Whichever route you use, it is an ordinary inbound USDC transfer on Arc Testnet — there is no special deposit contract, and you can verify the balance yourself on Arcscan.

Three things come out of that one balance on every settlement: your share of the bill, the job fee(0.01 USDC by default, escrowed and released to the agent that did the work), and the agent's own gas. Before it starts, the agent checks it holds the fee plus a 0.20 USDC gas headroom plus the share itself; short of that it skips with agent_unfunded and opens no job, so an underfunded agent costs you nothing. Top it up and the next bill settles.

Three agents on every job

The settlement itself is not a single hidden server call. It is an ERC-8183 job on the already-deployed AgenticCommerce contract on Arc Testnet, with three distinct wallets in three roles, so no agent ever grades its own work:

The bill review is bought, not asked for

"Check the bill's contents before paying" is not a free internal function call. The Auditor sells that verdict at $0.002 per review and the Settler buys it over x402 — the same HTTP 402 Payment Required protocol Scout uses — paying out of the fee income it earns from completed jobs. The review weighs the merchant, total and your share against each other; it is given headline figures only and never the receipt image, so it cannot tell who ordered what.

Every failure direction is a refusal: a 402, a timeout, an unparseable verdict, a missing key, or a failed x402 settlement. A Settler that cannot buy a review settles nothing.

Splitsy's paid endpoints

All three are open to anyone who pays — that is what makes them a market rather than an internal call. Each is settled by Circle's batch facilitator against an offchain EIP-3009 authorization, so the buying agent spends no gasto pay, and both sides of every payment are recorded in Splitsy's x402 ledger.

Reading the decision log

Every bill your agent looked at leaves a row, including the ones it refused — the refusals are the point, because they are what shows a spending permission is still constrained. Each row carries the bill, the amount, the decision, and a reason:

A settled row expands into its job trail: every transaction of the ceremony with its block number and hash, the job's live status read from the contract, and the x402 payments that gated it, each linking to Circle's own receipt. The status stored on the row is a display mirror; the contract is the source of truth.

The last three are deliberately logged as a payment for the full amount whenever the money might have moved, and they count against your daily ceiling. Costing you headroom you were entitled to is recoverable; handing back a cap you had already spent is not.

What it costs to run

Two USDC approvals sit outside those six. They are lazy — sent only when the current allowance is short, and for 100× the amount being spent — so they amortise across roughly a hundred settlements instead of landing on each one.

When you upload a receipt, Splitsy does not scan it directly. The upload is handed to Scout — an autonomous agent with its own wallet, its own ERC-8004 on-chain identity, and a daily spending budget. Scout decides whether your photo is worth scanning, then pays Splitsy's own scanning API in USDC, per call, over Arc. If the first read looks shaky it buys a second opinion out of its own budget.

This is a real machine-to-machine economy, not a metaphor: every scan is an HTTP request that gets answered with 402 Payment Required, a USDC payment authorization, and only then the parsed bill. You never pay for it and never see a prompt — the agent's spending is its own.

What a single scan actually does

What Scout charges itself

So a clean USD receipt costs the agent $0.005; a blurry euro receipt costs $0.011. Both sides of every payment are recorded — what Splitsy earned as the seller and what Scout spent as the buyer — and the dashboard's Scout's x402 ledgerpanel shows the running totals, the budget left for the day, and the last payments with a link to Circle's receipt for each. Scout is not the only agent that pays this way: see Autopay Agents for the review the Splitsy Settler buys before every settlement.

Scout's wallet and on-chain identity

Scout does not use a Circle wallet like yours. It holds a dedicated server-side account on Arc whose onlyjob is signing x402 payment authorizations — deliberately separate from every user wallet, and funded with a small amount of test USDC deposited into Circle's Gateway so its payments can be batched.

It is also registered as an agent on the same ERC-8004 IdentityRegistry that gives payers their reputation NFTs (0x8004A818BFB912233c491871b3d84c89A494BD9e), via register(metadataURI). That means the agent that scanned your receipt has a publicly checkable identity: the scan result shows "scanned by agent 0x… — see its onchain identity" and links straight to Arcscan.

Once you have joined a few bills, what you owe and what you are owed is scattered across all of them. The dashboard's Treasury tab collapses that into one net figure per person — and a single Settle net button that discharges every open position at once.

What Settle net costs to run

Settling bill by bill means an approval plus a payment for every debt, and a claim for every bill you are collecting on — 2 × debts + claims transactions in total. What replaces that depends on which wallet signs:

The asymmetry is not arbitrary. Splitsy's social wallets are Circle smart contract accounts, which can execute a batch of calls as one atomic transaction; a connected browser wallet is a plain externally-owned account, which cannot, so it still signs each leg. Either way a single USDC approval covers every payment instead of one approval per bill.

Settling from your Splitsy wallet

Reading the Treasury tab

• Owed to me — the sum of every unpaid share on bills you created.
• I owe — the sum of every unpaid share you hold on other people's bills.
• Net position — the difference. Positive means you are owed on balance; negative means you owe.
• Claimable now — money already paid into your bills that you have not yet withdrawn.
• Per person, both directions are shown alongside the net, labelled with their handle where Splitsy knows it and a shortened address where it does not.
• The tab shares the dashboard's wallet scope selector. With both a Splitsy wallet and a browser wallet connected you must pick which one settles, because each signs differently.
• On sample data (?demo=1) the figures render but settling is disabled.

Contracts are intentionally narrow. They store the minimum accounting state needed for payment enforcement and emit events for app indexing, explorer review, and user-facing history.

The payment contracts build on a small set of shared, audited security primitives rather than external dependencies. Each is intentionally minimal and carries no owner, upgrade, or privileged path.

Recurring settlement is designed to be automatic after user approval. Payers maintain enough USDC and allowance for the tab, while Splitsy periodically checks whether a cycle is due and collectible.

If a payer has insufficient balance or allowance, the contract records a shortfall and Splitsy can collect the unpaid portion later after the payer funds or re-approves their wallet. Recipients can claim collected funds when a claimable balance is available.

Autopay agents are the debtor-side equivalent and are funded by the user, not by the operator: an agent that runs out of USDC skips with agent_unfunded and creates nothing on chain, so restoring it is a top-up rather than an operator action. The Splitsy Settler and Auditor pay for their own transactions out of their own balances, and an unset settlement configuration reads as autopay off— never as "settle without the job".

• Users explicitly approve USDC spend before contracts can pull funds.
• Recurring approval is constrained to the tab contract address and can be revoked by setting allowance to zero.
• Recurring settlement is protected by operational controls and is not exposed as a public user action.
• Every fund-moving entrypoint follows checks-effects-interactions and is guarded by the shared ReentrancyGuard (nonReentrant) module.
• All USDC movement routes through the SafeERC20 library, so a token that returns no data or false can never be treated as a successful transfer.
• Contracts hold no privileged owner and expose no upgrade, pause, sweep, or selfdestruct path; funds can only ever leave to a bill's splitter or a tab's immutable recipient.
• Sensitive operational credentials must never be exposed in browser code, screenshots, public docs, or client logs.
• Contracts use custom errors and explicit checks for invalid amounts, unknown bills, unauthorized claims, and duplicate recurring members.
• Receipt OCR data should be reviewed by the splitter before submission. The scanner is a convenience layer, not an accounting authority.
• Bridge flows depend on the connected wallet signing each step and on Circle attestation for CCTP minting.
• Payment reputation is consent-based and positive-only: a score can only be created by a payment the wallet itself made, and every entry is re-verifiable against the on-chain payment it commits to (see Payment Reputation).
• An autopay agent spends only the USDC you transferred to it — Splitsy holds no allowance on your own wallet for it — so its balance is a hard ceiling no rule, bug, or compromised server can exceed.
• Each settlement job uses three distinct wallets for client, provider, and evaluator, so the agent that is paid for a job is never the agent that decides it was done. The evaluator re-reads the registry on chain rather than trusting the provider's claim.

Splitsy should be connected to the intended Arc Testnet contracts before users create bills or recurring tabs. Contract addresses, USDC token settings, bridge support, receipt scanning, and settlement automation are managed by the operator during deployment.