Coven documentation
Everything about Coven in one place: joining the testnet, using every feature, what it costs, how your money is protected, and how it is built.
What is Coven
Coven is a social payments app for USDC. Send to an @username, split bills with friends, save toward a shared goal, and cash out to a local bank account.
Coven is a payments app, not a crypto wallet. You sign in with Google, claim a permanent @username, and pay people by name instead of by a 42-character address. There is no seed phrase to write down and no second token to buy for fees.
Every account is backed by a Circle Programmable Wallet that you control with a PIN. Payments settle on Arc, a blockchain built for payments where USDC is also the gas token, so a payment is final in under a second and costs about a cent.
| Feature | What it does |
|---|---|
| @usernames | A permanent handle so people can pay you by name |
| Send & request | One-tap payments and payment requests, with decline |
| QR payments | Show a code, get paid. Optional fixed amount for merchants |
| Circles | Groups with a shared activity feed and group sends |
| Bill splits | Each member's share is held in an escrow contract until everyone has paid |
| Savings goals | Pool money toward a target; releasing it needs every member's approval |
| Cash out | USDC to NGN, GHS, KES or ZAR in a bank account via Yellow Card (not on testnet) |
Why Arc
- USDC pays the fee. Someone who has just received money can spend it straight away, without first buying another token for gas.
- Final on inclusion. One confirmation is final and blocks arrive about every half second, so the app treats a payment as settled as soon as it lands.
- Stable, low fees. About $0.01 per transaction, so the app can show you a real fee in dollars.
Testnet
Coven's public testnet opened on 9 November 2026 on Arc Testnet. Every dollar on testnet is free testnet USDC with no real value.
The testnet is where we find what breaks before real money is involved. Use every feature, try odd amounts, invite friends, and report anything that looks wrong. Completing the core flows makes you eligible (see Eligibility). The testnet whitepapersets out the testnet's objectives, eligibility and fair-play policy in full.
| Where | Link |
|---|---|
| App | covenpay.vercel.app |
| Testnet whitepaper | Download the PDF |
| X | @Covenpay |
| Telegram | Coven testnet group |
| USDC faucet | faucet.circle.com |
| Block explorer | explorer.testnet.arc.io |
| Source code | GitHub |
Only trust official links
What is live on testnet
| Feature | Status |
|---|---|
| Sign up, @username, wallet | Live |
| Send, request, QR | Live |
| Circles and circle sends | Live |
| Bill splits (SplitEscrow) | Live |
| Savings goals (GoalPool) | Live |
| Invites and referrals | Live |
| Cash out to a bank | Not part of the testnet |
| Paying in from other chains | Coming later (see Cross-chain payments) |
Getting started
You need a Google account and about five minutes. No MetaMask, no seed phrase, no gas token.
- 1Open Coven and sign in with Google.
- 2Claim your @username. It is permanent, so choose one you want to keep.
- 3Set your wallet PIN. Coven creates a Circle wallet on Arc for you, and every payment needs this PIN. Write it down somewhere safe; it cannot be reset by anyone else.
- 4Open Receive and copy your wallet address (it starts with
0x). - 5Go to faucet.circle.com, choose Arc Testnet and USDC, paste your address and request funds.
- 6Back in Coven, your balance on Home goes up within a few seconds. You are ready.
Keep a little USDC for fees
Wallet setup failed or was interrupted?
Reload the app and sign in again, then finish setting your PIN. If it still fails, report it with your @username (see Reporting a bug).
Eligibility
You are eligible once you have completed all 6 required stages. The team checks this automatically from on-chain transactions and invite records, so there is nothing to submit.
| Stage | What you do | What counts | Contract | Required |
|---|---|---|---|---|
| Wallet set up | Sign in, claim @username, set PIN | A Coven wallet on your account | Circle wallet | Yes |
| Funded | Claim testnet USDC from the faucet | A deposit into your Coven wallet | USDC | No, but later stages need funds |
| Create a circle | Create a circle with at least one other tester | One circle you created | None (off-chain) | Yes |
| Send money | Send USDC to an @username or inside a circle | One completed send | USDC transfer | Yes |
| Split a bill | Create a bill split, or pay your share of one | One split created or paid | SplitEscrow | Yes |
| Contribute to a goal | Put USDC into a circle savings goal | One contribution | GoalPool | Yes |
| Invite a friend | Share your invite link from Settings | One friend who signs up through it and sets up a wallet | None (off-chain) | Yes |
Bonus activity is recorded but does not change eligibility: total transactions, USDC moved, goals created, and any invites beyond the first.
Fair play
- One account per person. Clusters of new accounts moving the same funds in a loop may be removed.
- Only transactions made through the Coven app count. Sending USDC to a contract from another wallet does not.
- Requirements may change during the testnet. Changes are announced in the official channels and on this page.
How activity is counted
The core team tracks every verified testnet transaction and each tester's progress on an internal tracker.
Each transaction you make through Coven is recorded with what it did and which contract it went through. Your stages are ticked from those records and from your invite link, so you do not need to submit anything. The tracker itself is only open to the Coven team; to check your own progress, open Settings → Testnet.
| Tracker label | What happened | Contract |
|---|---|---|
| Send | USDC sent to an @username | USDC transfer |
| Circle send | USDC sent to a member inside a circle | USDC transfer |
| Split created | A bill split was opened | SplitEscrow |
| Split paid | A member paid their share of a split | SplitEscrow |
| Goal created | A savings goal was opened | GoalPool |
| Goal contribution | USDC put into a goal | GoalPool |
| Goal payout | A goal released its funds | GoalPool |
| Deposit | USDC arrived from outside Coven, such as the faucet | Inbound USDC |
The tracker lists usernames and wallet addresses, never emails or phone numbers. Only transactions the server has verified on-chain are recorded, so a failed or abandoned payment never appears.
@usernames
Your @username is how people find and pay you. It is permanent.
- 3 to 20 characters: letters, numbers and underscore.
- Not case-sensitive: @Ada and @ada are the same account.
- Some names are reserved, such as
coven,admin,support,helpandofficial. - Your public profile is at
/profile/yourname.
Sending money
Pay anyone on Coven by @username. Same-chain payments carry no Coven fee.
- 1Tap Send and search for an @username.
- 2Enter the amount and an optional note.
- 3Check the recipient and the amount, then confirm with your PIN.
- 4The payment lands in under a second and shows in History for both of you.
Payments are final
Requests
Ask someone to pay you a set amount. They pay or decline in one tap.
- Go to Request, choose an @username, the amount and a note.
- The other person is notified and can pay (with their PIN) or decline.
- A request that is not answered expires after 7 days.
- Requests waiting on you are shown on Home.
QR payments
Get paid in person by showing a code.
- Open QR: on Receive, show your code. The payer chooses the amount.
- Merchant mode: set a fixed amount and the code carries it, so the customer only confirms.
- To pay, open Scan, point the camera at the code, check the details and confirm with your PIN.
Circles
A circle is a group of people who pay each other often: flatmates, a team, family.
- 1Go to Circles and choose New circle.
- 2Name it and add members by @username. Members must already have Coven accounts.
- 3Everyone in the circle sees its activity feed: sends, splits and goals.
Inside a circle you can send to one member or to everyone. Sending to everyone makes one payment per member, and each needs your PIN. Bill splits and savings goals also live inside a circle.
Bill splits
Split a bill and let an escrow contract collect it. You are paid once everyone has paid.
Splits run on the SplitEscrow contract. Each split gets its own small custody contract, so money in one split is never mixed with another.
- 1Open a circle and choose New bill split.
- 2Describe it, enter the total, and choose who owes what. Confirm with your PIN; this creates the split on-chain with you as the recipient.
- 3Each member opens the split and pays their share with their PIN. The money is held in escrow, not sent to you yet.
- 4When the last share is paid, the escrow pays you the full amount automatically.
If not everyone pays
- A split has a deadline: 72 hours by default, up to 30 days.
- The creator can cancel an open split at any time.
- After the deadline anyone can expire it.
- Once a split is cancelled or expired, each member who paid claims their own refund from the split.
| Rule | Value |
|---|---|
| Members per split | Up to 50 |
| Deadline | 72 hours by default, 1 hour to 30 days |
| Who receives | The split's creator, who does not owe a share |
| A member pays | Exactly their share, once |
Savings goals
Save toward a shared target. Nobody, including the creator, can take the money out alone.
Goals run on the GoalPool contract. Like splits, each goal has its own custody contract.
- 1Open a circle and choose New savings goal. Enter what you are saving for and a target, then confirm with your PIN.
- 2Any member contributes any amount, as often as they like, with their PIN.
- 3When it is time to spend, one member requests a withdrawal to a recipient. That request counts as their approval.
- 4Every other member approves the same recipient and amount. When the last approval lands, the money is released automatically.
Rules that protect the pot
- Only one withdrawal request can be open at a time. The person who requested it can cancel it.
- Contributions pause while a withdrawal is waiting for approval.
- Each approval names the recipient and amount. If the request is different from what you were shown, your approval is refused.
- If someone stops responding, any member can start an exit. After a 30-day countdown the goal can be dissolved and every member claims back exactly what they put in. The member who started the exit can cancel it.
History & notifications
Everything that moves through your account, in real time.
- History lists your sends, receipts, requests, splits and cash outs, with filters and in/out totals.
- The bell shows notifications: payments received, requests, split and goal updates, approvals waiting on you.
- Balances and feeds update live without refreshing the page.
- Money sent to your address from outside Coven (for example the faucet) appears as a deposit.
Invites
Share your invite link and see who joined through it.
Your link is in Settings and looks like /r/yourname. Someone who signs up through it is recorded as invited by you, once, and only for a new account. You cannot invite yourself. Your invite count is shown in Settings. A friend who joins through your link and sets up a wallet completes your Invite stage.
Cash out
Turn USDC into local currency in a bank account. Not part of the testnet.
Cash out sends USDC to Coven's collection wallet and pays local currency into your bank account through Yellow Card. It covers Nigeria (NGN), Ghana (GHS), Kenya (KES) and South Africa (ZAR). Coven charges 1%, shown before you confirm, plus the exchange rate quoted by Yellow Card. Bank account numbers are encrypted before they are stored.
On testnet
Cross-chain payments
Paying in from Ethereum, Base, Polygon and other chains. Coming later.
Coven uses Circle's CCTP to move USDC from another chain to Arc: the USDC is burned on the source chain and minted on Arc, so there is no bridge or wrapped token. The relay and attestation are built; the screen for paying from an outside wallet is still in progress. Cross-chain payments carry a 0.5% fee.
Fees & limits
What things cost and the limits the contracts enforce.
| Action | Coven fee | Network fee |
|---|---|---|
| Send, request, QR, circle send | None | About $0.01 |
| Create or pay a bill split | None | About $0.01 |
| Create, contribute to or withdraw from a goal | None | About $0.01 |
| Cross-chain payment in (coming) | 0.5% | Source chain fee |
| Cash out to a bank (not on testnet) | 1% | About $0.01, plus Yellow Card's rate |
| Limit | Value |
|---|---|
| @username length | 3 to 20 characters |
| Request expiry | 7 days |
| Members per bill split | 50 |
| Bill split deadline | 1 hour to 30 days (default 72 hours) |
| Open withdrawal requests per goal | 1 |
| Goal exit countdown | 30 days |
How a payment works
From your PIN to the other person's balance in under a second.
- 1Send. You choose an @username and an amount and enter your PIN.
- 2Sign. Your device completes a Circle PIN challenge and signs the transfer. The server never sees your PIN and cannot start a transfer for you.
- 3Settle. The transaction lands on Arc. It is final on inclusion.
- 4Verify. The server fetches the transaction from Circle and the chain itself and checks the wallet, recipient and amount before recording anything. A made-up transaction id is refused, and one transaction can only be recorded once.
- 5Notify. Both sides see the payment immediately in their feed, balance and notifications.
Splits and goals work the same way: your PIN signs the contract call, then the server reads the result from the chain (the events the contract emitted) and records only what the chain says happened.
Security
Your money stays under your control, and the app records only what the chain confirms.
- Non-custodial wallets. Wallets are user-controlled Circle Programmable Wallets. Coven stores no private keys and cannot move your funds without your PIN.
- Server-verified settlement. Nothing is marked paid because the app said so; it is checked on-chain first.
- Escrow and unanimous approval. Split money waits in escrow until everyone has paid. Goal money needs every member's approval to leave.
- Isolated custody. Each split and each goal holds its money in its own contract, so a problem with one cannot freeze another.
- Approvals bound to details. Paying a split or approving a goal withdrawal names the recipient and amount; a mismatch is refused on-chain.
- Encrypted bank details. Account numbers are encrypted with AES-256-GCM before storage.
- Row-level security. Database rules limit every read and write to the signed-in user.
- Network guard. A mainnet deployment refuses to run with testnet settings left in, and a testnet one refuses a live Circle key.
Protect yourself
Smart contracts
Coven's contracts on Arc Testnet. Written in Solidity 0.8.24 with OpenZeppelin, tested with Foundry.
| Contract | Address | Used for |
|---|---|---|
| SplitEscrow | 0x2aE96b391a9cd89fFFCeDC1c1528E1CEC79DEE35 | Bill splits |
| GoalPool | 0xf07D6A07313C3D470f8D3305ABC659fDD2462563 | Savings goals |
| PayCircle | 0x6F76236742b87376Ef7d27E12968C796081Ed068 | Fee-bearing sends (deployed, not yet used by the app) |
| USDC (ERC-20, 6 decimals) | 0x3600000000000000000000000000000000000000 | The money itself |
SplitEscrow
Holds each member's share until the split is complete, then pays the recipient. Refunds are pulled by each member.
| Function | Who | What it does |
|---|---|---|
createSplit(members, amounts, recipient, description, deadlineHours) | Creator | Opens a split and deploys its custody contract |
pay(splitId, expectedRecipient, expectedAmount) | Member | Pays your share; reverts if the details differ |
cancel(splitId) | Creator | Closes an open split so payers can claim refunds |
expire(splitId) | Anyone | Closes a split after its deadline |
claimRefund(splitId) | Member who paid | Returns your share from a closed split |
Events: SplitCreated, MemberPaid, SplitComplete, SplitCancelled, Refunded.
GoalPool
Pools contributions toward a target. Funds leave only by unanimous approval, or through the time-locked exit.
| Function | Who | What it does |
|---|---|---|
createGoal(members, targetAmount, description) | Creator | Opens a goal and deploys its custody contract |
contribute(goalId, amount) | Member | Adds USDC to the pot |
requestWithdrawal(goalId, recipient) | Member | Proposes releasing the pot to a recipient |
approveWithdrawal(withdrawalId, recipient, amount) | Member | Approves; the last approval releases the funds |
cancelWithdrawalRequest(withdrawalId) | Requester | Withdraws the proposal |
startExit(goalId) / cancelExit(goalId) | Member | Starts or stops the exit countdown |
dissolve(goalId) | Member | Closes the goal after the countdown |
claimRefund(goalId) | Member | Returns your own contributions after dissolving |
Events: GoalCreated, Contributed, WithdrawalRequested, WithdrawalApproved, WithdrawalExecuted, WithdrawalCancelled, ExitStarted, ExitCancelled, GoalCancelled, Refunded.
PayCircle
Fee-bearing single and group payments (up to 50 recipients) and cash-out fee collection. Fees go to a separate custody contract and are withdrawn by an owner wallet that is not a server key. It is deployed but the app does not route payments through it yet.
Arc network
Details for wallets, explorers and developers.
| Setting | Value |
|---|---|
| Network | Arc Testnet |
| Chain ID | 5042002 |
| RPC | https://rpc.testnet.arc.network |
| Explorer | explorer.testnet.arc.io |
| Gas token | USDC |
| Block time | About 0.5 seconds, final on inclusion |
| Typical fee | About $0.01 |
USDC has two faces on Arc
0x3600…0000 has 6. They are the same money. Coven and its contracts always use the 6-decimal ERC-20 interface.Architecture
A Next.js app, a Postgres database, Circle wallets and three contracts on Arc.
Next.js 16 app (mobile-first PWA)
Home · Send · Request · QR · Circles · Goals · Cash out
│ REST + Supabase Realtime
Next.js API routes (server)
PIN challenges · on-chain verification · CCTP relay
│ │ │
Supabase Circle Arc
Postgres Programmable SplitEscrow · GoalPool
Realtime Wallets, CCTP v2 PayCircle · USDC
Storage │
Yellow Card (cash out)| Layer | Choice |
|---|---|
| Frontend | Next.js 16 (App Router), React 19, Tailwind CSS 4 |
| Backend | Next.js API routes |
| Database | Supabase: Postgres, Realtime, Storage, row-level security |
| Auth | Supabase Auth with Google |
| Wallets | Circle Programmable Wallets, user-controlled |
| Chain | Arc (chain 5042002), USDC as gas |
| Cross-chain | Circle CCTP v2 (Arc is domain 26) |
| Cash out | Yellow Card |
| Contracts | Solidity 0.8.24, OpenZeppelin, Foundry |
Run it locally
Requires Node 22 or 24, pnpm, a Supabase project and a Circle developer account. Foundry for the contracts.
git clone https://github.com/MarvyNwaokobia/Coven.git
cd Coven/frontend
pnpm install
cp .env.example .env.local # fill it in; every key is documented there
pnpm dev # http://localhost:3000- Database: in the Supabase SQL editor run
supabase/schema.sql, then each file insupabase/migrations/in number order. - Auth: enable the Google provider in Supabase, and allow
<app url>/auth/callbackas a redirect URL. - Tests:
pnpm testruns the API route tests; the contract-backed ones need Foundry. - Contracts:
cd contract && forge install && forge test. Deploy scripts need--legacyon Arc.
API routes
The server routes the app calls. Routes that act for a user need the user's Supabase session token.
Money-moving actions are two steps: a …-challengeroute builds the transaction and returns a Circle challenge for the user's PIN, and a …-confirm route verifies the result on-chain and records it.
| Area | Routes |
|---|---|
| Account | /api/me · /api/users/create · /api/users/search · /api/users/[username] · /api/profile/avatar |
| Wallet | /api/circle/init · /api/circle/complete · /api/circle/status · /api/circle/transfer-challenge · /api/balance |
| Payments | /api/payments/send · /api/payments/request · /api/payments/[requestId]/pay · /api/payments/[requestId]/reject |
| Circles | /api/circles · /api/circles/create · /api/circles/[id] · /api/circles/[id]/send |
| Splits | /api/splits/create-challenge · create-confirm · [splitId]/pay-challenge · pay-confirm · action-challenge · action-confirm |
| Goals | /api/goals/create-challenge · create-confirm · [goalId]/contribute-* · withdraw-request-* · withdraw-approve-* · action-* |
| Activity | /api/activity · /api/history · /api/history/export · /api/notifications · /api/notifications/unread-count |
| Invites | /api/referrals · /api/referrals/claim |
| Cash out | /api/banks · /api/cashout/initiate · /api/cashout/[payoutId]/status |
| Public | /api/health |
| Core team | /api/testnet |
Health & operations
Two endpoints for running the testnet.
GET /api/health
Checks the configuration, the database and its migrations, the Arc RPC, the deployed contracts, the Circle API key, the relayer's gas and whether cash out is configured. Answers 200 when every critical check passes and 503 when one fails, so an uptime monitor can watch it directly. Anyone sees only { "ok": true }; the per-check detail needs the operator token (HEALTH_TOKEN, sent as a bearer token).
GET /api/testnet
The data behind the tracker: totals, stage counts, every tester's progress and the latest 100 transactions. Rebuilt at most every 30 seconds. It needs the team access code (TESTNET_ACCESS_CODE, sent as the x-access-code header) or a sign-in whose email is in TESTNET_TEAM_EMAILS. Without either it answers 401; a wrong code answers 403.
Daily checklist during the testnet
/api/healthreturns"ok": true.- The relayer wallet still holds testnet USDC.
- Someone on the team runs the full flow once: sign up, fund, circle, send, split, goal.
- New bug reports are triaged.
FAQ & troubleshooting
My faucet USDC is not showing.
The faucet says I have hit a limit.
I forgot my PIN.
A payment left my wallet but Coven does not show it.
I sent money to the wrong person.
I cannot contribute to a goal.
My split never completed.
Someone in my goal stopped responding.
How do I check my progress?
Do I need ETH or another token for gas?
Is testnet USDC worth anything?
Reporting a bug
A good report gets fixed fast.
Post in the official Telegram group or open an issue on GitHub, and include:
- 1Your @username.
- 2What you were doing and what you expected.
- 3What happened instead. A screenshot helps.
- 4The transaction hash or explorer link, if there is one.
- 5Your device and browser.
Never share your PIN
Glossary
| Term | Meaning |
|---|---|
| Arc | The blockchain Coven runs on, built for payments, with USDC as its gas token |
| USDC | A dollar stablecoin issued by Circle. 1 USDC is designed to equal $1 |
| Testnet | A practice network with free tokens that have no value |
| Faucet | A site that hands out free testnet tokens |
| Wallet address | Your account's public identifier on-chain, starting with 0x |
| PIN | The code that approves every payment from your wallet |
| Circle | A group in Coven (not to be confused with Circle the company) |
| Escrow | A contract that holds money until agreed conditions are met |
| Transaction hash | The unique id of a transaction, used to find it on the explorer |
| Explorer | A website that shows every transaction and address on the chain |
| CCTP | Circle's protocol for moving USDC between chains by burning and minting |
| Gas | The network fee for a transaction; on Arc it is paid in USDC |
Roadmap
What comes after the testnet.
- Paying in from other chains in the app (the CCTP relay is already built).
- Cash-out fees settled on-chain through PayCircle.
- Push and SMS notifications alongside the in-app feed.
- Cash out in more countries beyond Nigeria, Ghana, Kenya and South Africa.
- Mainnet launch on Arc.