Docs

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.

CorridorPayer sendsRecipient getsCounted against the caps
usdt-cngn
Default. Pay someone in naira
USD₮cNGNThe USD₮ sold
usdt-idrx
Pay someone in rupiah (Indonesia)
USD₮IDRXThe USD₮ sold
usdt-wars
Pay someone in Argentine pesos
USD₮wARSThe USD₮ sold
usdt-wcop
Pay someone in Colombian pesos
USD₮wCOPThe USD₮ sold
cngn-usdt
Pay someone in dollars
cNGNUSD₮The USD₮ bought
celo-cngn
Pay in naira from CELO. Owner payouts only
CELO (the agent's own)cNGN, after two swapsThe 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.

This website never holds money or keys. Every payment it helps with is sent from your own wallet, after you approve it there: paying a link or a Lokal tag, making a “Get paid” link, claiming a tag, or rating a payout. The agent, running on its owner's computer, converts on Textile FX and pays the recipient.

How a payout runs

src/pay.mjs

The 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.

  1. Quote

    Checks the recipient against the allow-list and asks Textile FX for a free preview. In usdt-cngn the caps are checked before any price is requested; in cngn-usdt they are checked on the dollars the preview would buy. A dry run stops here. With --execute it 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.

  2. 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.

  3. 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.

  4. 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.

Lokal tags and sign-in

assets/lokal-contracts.js · src/contract-watch.mjs

A 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.

  1. 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.

  2. 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.

  3. Share

    Your page is /@ada on lokalpay.vercel.app, or tag.html#ada on any copy of the site, with a QR code and a WhatsApp button.

  4. 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. setName changes or removes the display name; setReceiveToken sets 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 an NTP: 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.

Sign-in is checked by /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.ps1

lokal 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.

  1. Check

    Looks for Node.js 20 or newer and npm. Nothing is changed if they are missing.

  2. Download

    Fetches the code as a zip from GitHub (main, or the branch, tag or commit in $env:NTAG_REF) and installs its libraries with npm ci --ignore-scripts, so no package runs code while installing.

  3. Swap

    Checks the new copy starts, then puts it in %LOCALAPPDATA%\lokal\app in 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.

  4. PATH

    Writes the launcher %LOCALAPPDATA%\lokal\bin\lokal.cmd (plus ntag.cmd, the old name, so ntag still 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 | iex removes 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_REF pins a branch, tag or commit; $env:NTAG_NO_PATH = "1" leaves your PATH alone and prints the folder to add.
Your wallet is a separate file, %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.

The registry cannot check that a reviewer used the agent. “Verified payer” is our own check that the reviewing address has sent USD₮ or cNGN to the agent. Other ratings are shown as unverified.

Limits

Set in src/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 in src/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. For cngn-usdt it 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 in receipts.jsonl over 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. request refuses an amount whose cents suffix would pass MAX_USD, and a naira link worth more than MAX_USD at the current preview.
  • CELO payouts keep gas. A celo-cngn payout 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
CommandWhat it doesSends transactions
keygenCreates the agent wallet key file. Never overwrites an existing key and never prints it.No
statusShows 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
requestsLists 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
ntagsLists 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.

Quick start
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 in src/config.mjs
VariableDefaultWhat it controls
MAX_USD25Largest single payout, in USD.
MAX_DAILY_USD100Most USD paid out in any rolling 24 hours, counted from receipts.jsonl.
MAX_SLIPPAGE_BPS300How much worse the firm quote may be than the preview, in basis points (300 = 3%).
MIN_CELO_RESERVE2CELO the agent wallet must still hold after a celo-cngn payout, so it can pay gas.
CELO_GAS_MARGIN0.1CELO set aside for the gas of a celo-cngn payout itself (up to 7 transactions), on top of the reserve.
ATTRIBUTION_CODEcelo_7360953d1b53Tag added to every transaction. 1–32 characters of a–z, 0–9 and _.
AGENT_ADDRESS0x8a69…7a1eAgent address used when there is no key file: by request and by a dry-run watch.
SITE_URLhttps://lokalpay.vercel.appSite used in payment links and receipt links.
CELO_AGENT_KEY_FILE~/.celo-naira-agent/agent.jsonWhere the agent's private key is stored, outside the repo.
CONTACTS_FILEcontacts.jsonThe allow-list of recipients and your own wallets, in the repo folder. Git-ignored.
RECEIPTS_FILEreceipts.jsonlLog of executed payouts and unmatched deposits. The daily cap is counted from it. Git-ignored.
REQUESTS_FILErequests.jsonPayment requests and their status. Git-ignored.
WATCH_STATE_FILEwatch-state.jsonThe last block autopilot checked, so it resumes where it stopped. Written only with --execute. Git-ignored.
CELO_RPC_URLFornoRPC endpoint autopilot reads deposits from. Read in src/watch.mjs; other commands use Forno.
TEXTILE_APIhttps://api.textilecredit.com/v2Textile FX RFQ endpoint for previews and firm quotes.
ANTHROPIC_API_KEYNot setOptional. 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_MODELclaude-sonnet-5-5Model used by ask. Used only when ANTHROPIC_API_KEY is set.
File defaults are relative to the repo folder.

Contracts and addresses

Celo mainnet, chain 42220
The agent does not hard-code the reactor. It approves whichever contract Textile names in each firm quote.

FAQ

Can the website move money?
Not the agent's. The site holds no keys and reads public data from Celo (Forno RPC and Blockscout) and a published rate file. Payouts are sent only by the agent, on its owner's computer. Two pages hand something to your own wallet: a payment link's “Open in wallet” button fills in a transfer that you approve there, and a receipt can ask your wallet to send your rating of the payout. Neither can happen without your approval in your wallet.
Does autopilot need a server?
It needs one computer that runs 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?
Each open request has its own exact amount, so a given amount points to at most one link. If two deposits of that amount arrive, only the first one, in chain order, is paid. The second no longer matches an open request: it is logged as unmatched, is not paid, and stays in the agent wallet for the owner to return by hand.
Where does the exchange rate come from?
From free Textile FX previews, which include Textile's fee: $10 of USD₮ into each currency (naira, rupiah and both pesos; a thin market is read from a $1 preview, with the most Textile can convert right now) and ₦14,400 of cNGN for the dollar corridor. A currency that isn't quoting is shown as “Not available right now”. A GitHub Action fetches them every 30 minutes and publishes them with the site. If the naira preview is unavailable, the site falls back to Textile's market bid for USD₮/NGN and labels it as before fees. A real payout always uses a fresh firm quote at the time it runs.
Is it custodial?
The agent wallet is meant to hold funds only for the payout in progress: the payer funds it, and one run converts the deposit and pays it out. A deposit that matches no request stays in the agent wallet until the owner returns it. The owner keeps the private key in a local file. This website never holds funds.
What is the attribution tag?
A short code, 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?
Before converting, the agent compares the firm quote with the free preview. If the firm quote would deliver more than 3% less, it stops and sends nothing. If the quote expires while the approval is confirming, the swap is not sent. Run a manual payout again for a fresh quote. Under autopilot, the error is saved on the request and autopilot stops, so the owner decides what to do.
Can I pay from CELO?
The owner can, from the agent's own 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?
No. The optional AI only turns a request like “send $10 to ada” into a contact name and an amount. It never sees an address. Code then looks up the name in your contacts and applies the caps, the allow-list and the price check, exactly as for pay. Autopilot does not use the AI at all.