How it works
What the agent does, the rules it enforces in code, and how to run it yourself.
Overview
Lokal is a payout agent on Celo mainnet, with this website for people and a command line for its operator. It converts USD₮ into the recipient's local stablecoin through Textile FX (naira as cNGN, rupiah as IDRX, Argentine pesos as wARS, Colombian pesos as wCOP), and pays the result to the recipient: a contact saved by the agent's owner, the wallet that made a “Get paid” link, or the wallet behind a Lokal tag. Send money home to Lagos, Jakarta, Buenos Aires or Bogotá. Each route is called a corridor: pay someone in their local money, or (cNGN in) pay someone in dollars. The owner can also pay someone in naira from the agent's CELO (celo-cngn): Textile has no direct CELO to cNGN pair, so the agent makes two swaps, CELO to USD₮ and then USD₮ to cNGN, and pays two Textile fees.
The owner can run a single payout by hand, or create a payment link for an exact amount. When the payer sends that amount, autopilot matches the deposit, converts it and pays the contact. After every payout the agent prints a receipt link that rebuilds the payout from chain data, and the payer can rate it in the agent's onchain reputation registry.
Onchain: the agent's ERC-8004 identity (agent #10079), and every transaction it sends during a payout: the approval (and an allowance reset, if one is needed), the swap and the transfer to the recipient. Each one carries the attribution tag celo_7360953d1b53. Off chain, on the owner's computer: the Textile price quotes, the contacts file, the agent's key file, the payment requests file and a local receipts log.
| Corridor | Payer sends | Recipient gets | Counted against the caps |
|---|---|---|---|
usdt-cngnDefault. Pay someone in naira | USD₮ | cNGN | The USD₮ sold |
usdt-idrxPay someone in rupiah (Indonesia) | USD₮ | IDRX | The USD₮ sold |
usdt-warsPay someone in Argentine pesos | USD₮ | wARS | The USD₮ sold |
usdt-wcopPay someone in Colombian pesos | USD₮ | wCOP | The USD₮ sold |
cngn-usdtPay someone in dollars | cNGN | USD₮ | The USD₮ bought |
celo-cngnPay in naira from CELO. Owner payouts only | CELO (the agent's own) | cNGN, after two swaps | The USD₮ the first swap buys |
Amounts are always typed in the token the payer sends: USD₮ for every usdt-… corridor, naira for cngn-usdt, CELO for celo-cngn. Payment links, “Get paid”, Lokal tags and autopilot support every corridor except celo-cngn. Each token keeps its own decimals (cNGN 6, IDRX 2, wARS and wCOP 18); amounts shown to people are rounded down, and the agent pays exactly what the swap delivered. If a currency isn't quoting on Textile when a payment arrives, the agent refuses it (currency_unavailable) and never pays it in another currency. A cNGN recipient can redeem it for naira, for example through cngn.co.
How a payout runs
src/pay.mjsThe same steps run for every corridor. “Sell token” is what the payer sends (USD₮ or cNGN); “buy token” is what the recipient gets. For celo-cngn the Quote and Convert steps run twice, CELO to USD₮ and then USD₮ to cNGN, and the second swap sells only the USD₮ the first one delivered.
Quote
Checks the recipient against the allow-list and asks Textile FX for a free preview. In
usdt-cngnthe caps are checked before any price is requested; incngn-usdtthey are checked on the dollars the preview would buy. A dry run stops here. With--executeit confirms both tokens use 6 decimals, that the wallet holds the sell amount and about 0.02 CELO for gas, asks you to type “yes”, then requests a firm quote.Convert
Checks the firm quote against the preview (and, for
cngn-usdt, the caps again). If the current allowance is too low, approves exactly the sell amount the quote needs, to the contract the quote names (resetting an old allowance to zero first). Then it broadcasts Textile's swap transaction. An expired quote is never sent.Pay
Measures the agent's buy-token balance before and after the swap and transfers that difference to the recipient, never more than the swap itself delivered to the agent. A deposit that lands at the same moment is not paid on. No estimate is used.
Check
Reads every transaction it sent back from the chain (reset, approval, swap, payout), flags any that is missing the tag and exits with an error if one is. It prints Celoscan links and a receipt link, and appends the payout to
receipts.jsonl.
Payment links and autopilot
src/requests.mjs · src/watch.mjsA payment link asks someone to send an exact amount to the agent. When that amount arrives, autopilot pays the contact named on the link. Requests live only on the owner's computer, in requests.json; the link itself carries the public details (name, amount, corridor, note and expiry) and nothing is stored on a server.
Request
The owner runs
requestwith a contact fromcontacts.json, an amount and a corridor. The agent adds a random 0.01–0.99 to the amount so it differs from every other open request, and keeps it within the per-payout cap.Link
It prints the exact amount and a
pay.html#r=…link, valid for 48 hours unless--hourssays otherwise (up to 168). The payer opens it and sends exactly that amount from any Celo wallet.Match
watchreads token transfers to the agent from Celo. A deposit matches a request only when the token is the request's sell token, the value is the exact amount, and it arrived after the request was made and before it expired.Pay
With
--execute, it first runs the checks that send nothing: the contact, both caps and a live price. If one fails, it records nothing and stops before that deposit, so the request is not used up and the deposit matches again once the owner fixes the cause and restarts. Otherwise it records the payer and deposit on the request, then runs the normal payout above for that request's contact, amount and corridor. Without--executeit prints what it would do and saves nothing.
What autopilot never pays
- A deposit with no request. If no open request has that token and exact amount, the deposit is logged as unmatched and left in the agent wallet for the owner to handle.
- A request twice. The deposit is saved on the request before paying, so one request gets at most one payout, even after a crash.
- Anyone outside the contacts file. The name on a link is looked up in
contacts.jsonwhen the request is created and again when it is paid. - Over the limits. Every autopilot payout goes through the same per-payout and 24-hour caps as a manual one.
- A failed payout again. If a payout fails, the error is saved on the request, it is not retried automatically, and autopilot stops. The owner can run
retryfor that request, which refuses once a swap or payout was sent. - Its own transfers. Tokens that reach the agent from its own transactions, such as the output of a swap, are ignored.
watch-state.json and stops cleanly with Ctrl+C.
See autopilot activity
Lokal tags and sign-in
assets/lokal-contracts.js · src/contract-watch.mjsA Lokal tag is a short name, like @ada, tied to one Celo wallet. Anyone can pay a tag from their own wallet, and the agent pays the wallet that holds it. Tags live on the LokalTags contract on Celo, not on a server, and the contract checks every rule and limit before any money moves.
Sign in
On Account, connect your wallet and sign a short message. It's free, sends nothing and lasts 7 days. Signing out forgets it and disconnects the wallet.
Claim
Pick a tag and call
claim("ada", "Ada Obi")on LokalTags from your wallet (the display name is optional). The page simulates it first, so a refusal is explained before your wallet opens. It costs only the network fee.Share
Your page is
/@adaon lokalpay.vercel.app, ortag.html#adaon any copy of the site, with a QR code and a WhatsApp button.Get paid
The payer pays your tag through the contract with USD₮ (you get naira, rupiah or pesos, whichever they pick; your optional default is pre-selected) or cNGN (you get dollars). The money goes straight to the agent, which converts it and pays your wallet.
Rules
- Tag format. 3 to 20 characters: lowercase letters, numbers and
_. It starts with a letter, has no__and doesn't end with_. A few names, such as admin, support, celo, naira and lokal, are reserved. - First claim wins. The contract refuses a claim for a tag someone already holds (
TagTaken); nothing changes. - One tag per wallet. Claiming a new tag gives up your old one.
release()gives it up without a new one.setNamechanges or removes the display name;setReceiveTokensets your optional default currency. - 30-day lock. A tag you give up stays reserved for you for 30 days, so nobody can grab it and take your payments. You can claim it back within that time.
- Paying a tag. USD₮ from $1 up to $25 per payment, or cNGN from ₦1,500 up to $25 in value. The contract refuses anything over its limits per payment, per recipient and per payer per UTC day, and payments to an unknown tag or from the owner's own wallet, before any money moves. The agent's own caps still apply on top.
- Refused means refundable. If the agent refuses a payment the contract accepted, it records why, and the money can be sent back to the wallet it came from ("Refunded · RF-XXXX-XXXX").
- Older memo tags. Tags claimed with the older
NT1:transactions before block 83,405,000 keep being paid when someone sends them anNTP:memo payment. From that block on, new claims count only on the contract, and a name held in both places pays its contract holder. - Public and permanent. Tags, display names and the wallets that hold them are onchain. Anyone can read them and nobody can delete them.
Paying a tag without the website
Call payTagWithPermit(tag, USD₮, amount, ref, agent, deadline, v, r, s) on LokalTags after signing an EIP-2612 permit for exactly the amount, or approve exactly the amount and call payTag(tag, token, amount, ref, agent). The ref names what the owner receives: the ASCII text cur:idrx (or cur:cngn, cur:wars, cur:wcop, cur:usdt for dollars), left-aligned and zero-padded to 32 bytes; any other ref means the owner's default, else naira. lokal send ada 10 --to rupiah --dry-run prints the exact call. For an older memo tag, send an ERC-20 transfer(agent, amount) with the bytes of NTP:ada (or NTP:ada:idrx) after the usual 68 bytes of calldata.
/api/session only on lokalpay.vercel.app (and the older naira-payout.vercel.app address). That function verifies the signature and stores nothing. On GitHub Pages and the local preview there's no server, so the page trusts the signature your wallet returns. A sign-in never moves money: every transaction still needs your approval in your wallet.Install the lokal command (Windows)
install.ps1lokal pays a Lokal tag from your own wallet in PowerShell. To install it, open PowerShell (no admin needed) and paste this line. It takes about a minute.
irm https://lokalpay.vercel.app/install.ps1 | iex
You can read the script before you run it. It needs Node.js 20 or newer; if Node is missing it says so and stops (get it with winget install OpenJS.NodeJS.LTS or from nodejs.org). It never installs other software for you.
Check
Looks for Node.js 20 or newer and npm. Nothing is changed if they are missing.
Download
Fetches the code as a zip from GitHub (
main, or the branch, tag or commit in$env:NTAG_REF) and installs its libraries withnpm ci --ignore-scripts, so no package runs code while installing.Swap
Checks the new copy starts, then puts it in
%LOCALAPPDATA%\lokal\appin one rename. An install from before the rename, in%LOCALAPPDATA%\naira-payout, is removed and its PATH entry taken out. If anything fails, your previous install stays as it was.PATH
Writes the launcher
%LOCALAPPDATA%\lokal\bin\lokal.cmd(plusntag.cmd, the old name, sontagstill works) and adds that folder to your user PATH. Terminals that were already open need a restart.
Then
lokal wallet new # your wallet, protected by a send password lokal wallet # your address: add USD₮ and a little CELO for fees lokal whois ada # who owns the Lokal tag @ada lokal send ada 10 # you send $10 USD₮, @ada gets their preferred currency (else naira) lokal send ada 10 --to rupiah # ... and @ada gets rupiah (IDRX): "they get ≈ Rp 183,938"
In PowerShell a leading @ is special: write ada or '@ada'. lokal help lists every command, and the old name ntag still works; --dry-run shows a payment without sending it.
- Update. Run the same line again. The app folder is replaced; your wallet is not touched.
- Uninstall.
$env:NTAG_UNINSTALL = "1"; irm https://lokalpay.vercel.app/install.ps1 | iexremoves the app and bin folders and the PATH entry. By hand: delete both folders and remove the bin folder from your user PATH. - Options.
$env:NTAG_REFpins a branch, tag or commit;$env:NTAG_NO_PATH = "1"leaves your PATH alone and prints the folder to add.
%USERPROFILE%\.lokal\wallet.json (or NTAG_WALLET_FILE). A wallet made before the rename stays in %USERPROFILE%\.naira-payout\wallet.json and lokal keeps using it there. The installer never creates, reads, moves or deletes it. The key inside is encrypted with your send password, and there is no recovery: copy the file somewhere safe, for example Copy-Item $HOME\.naira-payout\wallet.json D:\backup\, and remember the password.Receipts and reviews
After every executed payout, from pay or from autopilot, the agent prints and logs a link of the form receipt.html#p=<payout>&s=<swap>, plus &r=<request> when it paid a payment link. The receipt page rebuilds everything from Celo in your browser: the token, amount and recipient of the payout, the amounts sold and bought in the swap and the effective rate, the time, and the attribution tag on each transaction. It can be shared on WhatsApp, copied or printed.
From a receipt, the payer can rate the payout from 1 to 5 stars. The rating is a giveFeedback transaction to the ERC-8004 Reputation Registry, sent from the payer's own wallet after they approve it there. The registry rejects ratings from the agent's owner or operators. The Agent page lists every rating with its average.
Limits
Set insrc/config.mjs$25 per payment · $25 per person per day · $100 per day overall
- $25 per payment (
MAX_USD), counted in dollars: the USD₮ sold, or the USD₮ bought when someone is paid in dollars. A “Get paid” link in naira can ask for $1 up to $24.99, so the payout stays under the $25 limit. - $25 per person per day (
MAX_WALLET_DAILY_USD) for “Get paid” links and Lokal tags: the agent adds up what it paid that wallet in the last 24 hours. A payment that would go over is refused and not paid out. - $100 per day overall (
MAX_DAILY_USD), across everyone, from the agent's own payout log. A payment that would go over it is not refused: autopilot stops before it, and pays it when it runs again with room under the limit.
“Per day” always means the last 24 hours, not a calendar day. A payment link shows how much more its recipient can receive today before you pay.
Safeguards
Enforced insrc/guards.mjs- Dry run by default. Nothing is sent without
--execute. A manual payout then waits for you to type “yes” (or pass--yes). - $25 per payout. Set by
MAX_USD. Forcngn-usdtit is checked on the preview, on the firm quote and on the dollars actually paid. - $100 in any 24 hours. Set by
MAX_DAILY_USD. The agent adds up the USD value of executed payouts inreceipts.jsonlover the last 24 hours and refuses a payout that would go over. - Only the named recipient. Owner payouts and owner links pay only contacts in the contacts file; a “Get paid” link pays only the wallet that registered it; a Lokal tag pays only the wallet that holds it. The agent's own address, the owner's
own_wallets, the token and registry contracts and the zero address are blocked. - Price protection. The firm quote may be at most 3% worse than the preview (
MAX_SLIPPAGE_BPS), and may not ask for more than the amount requested. Expired quotes are never sent. - Pays what it received. The payout is the measured change in the agent's balance, capped at what the swap delivered.
- Autopilot pays only matched requests. Exact token and amount, after the request was made and before it expired, one payout per request. Unmatched deposits are never paid, and autopilot stops on a payout error.
- Links stay within the cap.
requestrefuses an amount whose cents suffix would passMAX_USD, and a naira link worth more thanMAX_USDat the current preview. - CELO payouts keep gas. A
celo-cngnpayout must leave at least 2 CELO in the agent wallet (MIN_CELO_RESERVE) after the CELO sold and about 0.1 CELO for its own gas, because every network fee is paid in CELO. Otherwise it stops and says how much it could sell. - $1 minimum per swap, two swaps. Textile needs about $1 for each swap, so a CELO payout needs about 20 CELO (about $1.10 of USD₮ from the first swap). Each swap has its own Textile fee and its own price check, and the caps are checked on the USD₮ the first swap buys.
- Key stays local. The private key lives in a file outside the repo and is never printed.
- AI cannot override limits. The optional AI only maps a request to a contact name and an amount. Code applies every rule above.
Command line
node src/agent.mjs| Command | What it does | Sends transactions |
|---|---|---|
keygen | Creates the agent wallet key file. Never overwrites an existing key and never prints it. | No |
status | Shows the agent's CELO, USD₮ and cNGN balances, the tag, both caps, the USD paid in the last 24 hours and the number of open payment requests. Needs the key file. | No |
quote --amount N [--corridor ID] | Gets a free Textile FX preview. The amount is in the token the payer sends; without --amount it quotes 10 USD₮ or ₦14,400. No wallet needed. | No |
pay --to NAME --amount N [--corridor ID] [--execute] [--yes] | Runs a payout to a named contact. A dry run unless --execute is given; --yes skips the typed confirmation. | With --execute |
pay --to NAME --amount N --corridor celo-cngn [--execute] | Pays a contact in naira from the agent's CELO. The amount is in CELO (about 20 or more). Two swaps, CELO to USD₮ then USD₮ to cNGN, then the cNGN payout. Keeps 2 CELO for gas. Not available for payment links or autopilot. | With --execute |
ask "send $10 to ada" [--execute] [--yes] | Same as pay in the usdt-cngn corridor, from a plain-language request. | With --execute |
request --to NAME --amount N [--corridor ID] [--note TEXT] [--hours H] | Creates a payment link for a contact. Makes the amount unique, saves the request in requests.json and prints the exact amount and the link. --hours defaults to 48 (most 168); a note is up to 80 characters. | No |
requests | Lists every request with its status (open, received, paid or expired), amount, corridor, name, expiry and link, plus its deposit, receipt or error when there is one. | No |
watch [--execute] [--interval S] | Autopilot. Checks for deposits every --interval seconds (default 15, at least 5) and pays matched requests. A dry run unless --execute is given. | With --execute |
retry --request ID [--execute] [--yes] | Runs again an autopilot payout that failed after its deposit was recorded. Only for a request that is unpaid, has a saved error and sent no swap or payout. A dry run unless --execute is given; --yes skips the typed confirmation. | With --execute |
retry --ntag TX:LOGINDEX [--execute] [--yes] | The same, for a Lokal tag payment that failed after its deposit was recorded in ntag-payments.json. The id is the deposit transaction and its log index. | With --execute |
ntag <@tag | address> | Looks up a tag or a wallet: the owner, display name, since when, the claim transaction and whether the tag is free, taken, locked, reserved or invalid. | No |
ntags | Lists every tag held right now, with its owner and name. | No |
pay @tag <amount> [--corridor ID] [--execute] [--yes] | Pays a tag's owner from the agent's own funds. Looks the tag up now, re-checks the claim on Celo, then runs the normal payout with the same caps. In PowerShell write '@ada' in quotes, or use pay --ntag ada --amount 10. | With --execute |
ntag-data @tag <amount> [--token usdt|cngn] [--to-currency rupiah] | Prints the to and data for paying a tag from your own wallet or CLI. Never asks for a key. | No |
register [--repo URL] [--execute] | Registers the agent's ERC-8004 identity, then writes its id into the registration file. Needs the key file. | With --execute |
verify <hash> | Reads a transaction from Celo and shows the attribution tags it carries. Needs the key file. | No |
ID is usdt-cngn (the default), usdt-idrx, usdt-wars, usdt-wcop or cngn-usdt; --to-currency naira|rupiah|argentina-peso|colombia-peso picks a usdt-… corridor by name, and quote --all shows every currency at once. pay and quote also take celo-cngn; request does not. NAME must be a contact in contacts.json; case does not matter.
npm install npm test node src/agent.mjs keygen cp contacts.example.json contacts.json node src/agent.mjs quote --amount 10 node src/agent.mjs pay --to ada --amount 10 node src/agent.mjs request --to ada --amount 5 node src/agent.mjs watch
Add your recipient's address to contacts.json first. pay and watch without --execute are dry runs and send nothing.
Configuration
Environment variables, read insrc/config.mjs| Variable | Default | What it controls |
|---|---|---|
MAX_USD | 25 | Largest single payout, in USD. |
MAX_DAILY_USD | 100 | Most USD paid out in any rolling 24 hours, counted from receipts.jsonl. |
MAX_SLIPPAGE_BPS | 300 | How much worse the firm quote may be than the preview, in basis points (300 = 3%). |
MIN_CELO_RESERVE | 2 | CELO the agent wallet must still hold after a celo-cngn payout, so it can pay gas. |
CELO_GAS_MARGIN | 0.1 | CELO set aside for the gas of a celo-cngn payout itself (up to 7 transactions), on top of the reserve. |
ATTRIBUTION_CODE | celo_7360953d1b53 | Tag added to every transaction. 1–32 characters of a–z, 0–9 and _. |
AGENT_ADDRESS | 0x8a69…7a1e | Agent address used when there is no key file: by request and by a dry-run watch. |
SITE_URL | https:// | Site used in payment links and receipt links. |
CELO_AGENT_KEY_FILE | ~/.celo-naira-agent/ | Where the agent's private key is stored, outside the repo. |
CONTACTS_FILE | contacts.json | The allow-list of recipients and your own wallets, in the repo folder. Git-ignored. |
RECEIPTS_FILE | receipts.jsonl | Log of executed payouts and unmatched deposits. The daily cap is counted from it. Git-ignored. |
REQUESTS_FILE | requests.json | Payment requests and their status. Git-ignored. |
WATCH_STATE_FILE | watch-state.json | The last block autopilot checked, so it resumes where it stopped. Written only with --execute. Git-ignored. |
CELO_RPC_URL | Forno | RPC endpoint autopilot reads deposits from. Read in src/watch.mjs; other commands use Forno. |
TEXTILE_API | https:// | Textile FX RFQ endpoint for previews and firm quotes. |
ANTHROPIC_API_KEY | Not set | Optional. Lets ask understand free-form requests. Without it, a plain parser handles “send $10 to ada”. Read in src/intent.mjs. Never commit it. |
ANTHROPIC_MODEL | claude-sonnet-5-5 | Model used by ask. Used only when ANTHROPIC_API_KEY is set. |
Contracts and addresses
Celo mainnet, chain 42220| Name | Address |
|---|---|
| Agent wallet | 0x8a695cf54CB44753c8b784EB36d266f748617a1e |
| ERC-8004 Identity Registry | 0x8004A169FB4a3325136EB29fA0ceB6D2e539a432 |
| ERC-8004 Reputation Registry | 0x8004BAa17C55a88189AE136b182e5fdA19dE9b63 |
| USD₮ | 0x48065fbBE25f71C9282ddf5e1cD6D6A887483D5e |
| cNGN | 0xF6829D7393dAe24509eb1E52eE8e572e2E271a4f |
Textile LimitOrderReactor Per the hackathon brief | 0xa9AA0a64769cBed4d3B1Ceb4Df01CdE915C235b3 |
FAQ
Can the website move money?
Does autopilot need a server?
node src/agent.mjs watch --execute and holds the key file, such as the owner's laptop or a small server. It pays only while it is running. With --execute it saves the last block it checked, so after a restart it picks up deposits that arrived while it was off. A deposit sent before its link expired is still paid.What if two people send the same amount?
Where does the exchange rate come from?
Is it custodial?
What is the attribution tag?
celo_7360953d1b53, appended to the data of every transaction the agent sends, following ERC-8021. It credits the transactions to this hackathon entry. It is public, not a secret. You can check any transaction for it on the Verify page or with verify <hash>.What if the price moves?
Can I pay from CELO?
pay --to NAME --amount N --corridor celo-cngn. Textile has no direct CELO to cNGN pair, so the agent swaps CELO to USD₮ and then USD₮ to cNGN, paying a Textile fee on each, and sends the cNGN to the contact. Each swap needs about $1, so send about 20 CELO or more; the $25 cap applies to the USD₮ the first swap buys. The agent keeps 2 CELO for gas. There are no CELO payment links: payers send USD₮ or cNGN.Can the AI change the limits?
pay. Autopilot does not use the AI at all.