What ORYN is
ORYN is an autonomous treasury agent on Celo. You get a vault, a small smart contract that only you control. You tell it how to split incoming money, for example "30% to my designer, 20% to savings". From then on, every cUSD payment that lands in your vault is split automatically by the ORYN agent, onchain.
It is built for freelancers, creators and small teams who do the same bookkeeping every time they get paid. You describe the rule once and stop thinking about it.
Set up in four steps
- Connect a walletOpen the ORYN app and connect MetaMask or any browser wallet. It will offer to switch to Celo mainnet for you.
- Create your vaultClick Create my vault. One transaction, a fraction of a cent in gas. Each wallet gets exactly one vault.
- Set your splitOn the Set Rules tab, write your split in plain English, check the table ORYN builds from it, and sign. Do this before anyone pays you.
- Share your vault addressSend it to whoever owes you money. They pay in cUSD from the Deposit tab, and ORYN splits it automatically.
Writing your split
A rule is a recipient address and a percentage. You can have several. Whatever is left after all rules stays in your vault as savings.
Plain English works
Save a name for each recipient once (it is stored only in your browser), then write things like:
# one collaborator, rest saved pay designer 30%, rest stays as savings # two recipients pay designer 30% and editor 15%
ORYN turns this into a table you can edit before signing. Nothing is guessed silently: if a name isn't in your address book or the numbers don't add up, you'll see a warning instead of a transaction.
Worked example
Rules: designer 30%, editor 15%. A client pays 100 cUSD.
| Goes to | Share | Amount |
|---|---|---|
| Designer's wallet | 30% | 30 cUSD |
| Editor's wallet | 15% | 15 cUSD |
| Your vault savings | remainder | 55 cUSD |
Limits and details
- Percentages can add up to at most 100%. The contract rejects anything higher.
- Shares are stored in basis points (1% = 100 bps), so you can use values like 12.5%.
- Rounding always goes down; any dust lands in your savings, never somewhere else.
- You can change your rules any time. A new set fully replaces the old one and applies to the next split.
Getting paid
Your vault address is your payment address. Anyone can pay into it; they don't need a vault or an account. A payer needs:
- A browser wallet such as MetaMask.
- A little CELO for gas. A fraction of a cent is enough.
- cUSD for the amount. CELO can be swapped for cUSD non-custodially at app.mento.org.
In the app, the payer pastes your vault address on the Deposit tab and clicks Pay. The app handles the token approval and the deposit in order, and checks that the address really is an ORYN vault before anything is sent.
deposit(), so it isn't counted as a payment and won't be split. The owner can still withdraw it.How the agent works
The ORYN agent is a small always-on program with its own wallet. Its job is narrow:
- WatchEvery 15 seconds it checks Celo mainnet for new vaults and new deposits.
- SplitWhen a vault has an unsplit deposit, it calls
distribute()on that vault. The contract pays each recipient their share and credits the rest to savings. Splits usually land within about 30 seconds of a payment. - CategorizeFor each payout, the agent pays ORYN's bookkeeping service $0.01 in USDC over the x402 protocol to label it. The agent pays this from its own wallet, never from yours.
Every transaction the agent sends, and every transaction you sign in the app, carries ORYN's public attribution tag celo_2a23542d598e, so all activity can be independently traced. The agent is registered onchain under ERC-8004 as agentId 9688.
Security model
ORYN is non-custodial. The limits below are enforced by the vault contract itself, not by a policy or a promise.
| Action | You (owner) | ORYN agent | Anyone else |
|---|---|---|---|
| Pay into the vault | Yes | Yes | Yes |
Run the split (distribute) | Yes | Yes | No |
| Set or change rules | Yes | No | No |
| Withdraw funds | Yes | No | No |
| Replace or remove the agent | Yes | No | No |
The worst the agent can ever do is run your split at a moment you didn't choose, which only ever sends money where you already said it should go. If you want ORYN out entirely, call setAgent from your owner wallet and the agent loses even that.
onlyOwner and onlyAgentOrOwner modifiers.Withdrawing
Your savings sit in your vault until you move them. On the Withdraw tab, check your savings balance, enter an amount, and choose where it goes (your connected wallet by default). Only the owner wallet can withdraw, and there is no lock-up or fee.
Contracts & addresses
Everything runs on Celo mainnet (chain ID 42220).
Vault functions
| Function | Who | What it does |
|---|---|---|
deposit(amount) | Anyone | Pulls approved cUSD into the vault and marks it as waiting to be split. |
distribute() | Agent, owner | Splits everything waiting by the current rules; the remainder goes to savings. |
setRules(rules) | Owner | Replaces the split. Total must be at most 10,000 bps (100%). |
withdraw(amount, to) | Owner | Sends funds from the vault to any address. |
setAgent(agent) | Owner | Changes which address may trigger splits. |
Frequently asked
Does ORYN ever hold my money?
No. Your funds sit in your own vault contract, and only your owner wallet can withdraw or change rules. The agent can only trigger the split you already approved.
What does it cost?
ORYN takes no cut of your payments. You pay normal Celo gas (fractions of a cent) for transactions you sign: creating the vault, setting rules, withdrawing. The agent pays its own gas and x402 fees for every split.
How fast does a payment get split?
The agent checks every 15 seconds, so a split usually lands within about 30 seconds of the deposit confirming.
I got paid before setting rules. Where did the money go?
It's safe in your vault as savings. A vault with no rules keeps the whole deposit. Withdraw it any time, and set rules now so the next payment is split.
Can I change my split later?
Yes, as often as you like. A new set of rules replaces the old one and applies from the next split onward. Past splits are not changed.
What if the agent goes offline?
Nothing is lost. Deposits wait in the vault until a split runs. As the owner you can also call distribute() yourself, or withdraw directly.
Can I stop using the ORYN agent?
Yes. Call setAgent from your owner wallet with another address (or your own). The ORYN agent then has no permissions on your vault at all.
Which tokens are supported?
Vaults created in the app accept cUSD on Celo mainnet. The agent's own bookkeeping fees are paid in USDC.
Do the people I pay need anything?
Just a Celo-compatible wallet address. Their share arrives in that wallet as cUSD. They don't need a vault or to sign anything.
Is the code open source?
Yes. Contracts, agent and app are all on GitHub.
Glossary
| Wallet | An app like MetaMask that holds your keys and asks you to approve every transaction. |
| cUSD | A digital dollar on Celo (1 cUSD ≈ $1). The currency ORYN splits. |
| Vault | Your personal ORYN smart contract. It holds deposits and savings and enforces your rules. |
| Rule / split | A recipient plus a percentage. Your full split is the list of rules. |
| Savings | The part of each payment that no rule claims. It stays in your vault. |
| Non-custodial | No one but you can move your funds. ORYN only runs the split you approved. |
| Gas | The small network fee for a transaction, paid in CELO. |
| x402 | An open protocol for paying per request over HTTP. The agent uses it to pay for bookkeeping. |
| ERC-8004 | An onchain registry for AI agent identities. ORYN is agentId 9688. |