For developers and payroll operators
Run your own payroll on this code
The demo on this site is static. The API, the database and every adapter are played back inside your browser, which is why every button works and nothing needs a server. To pay people for real, you run the server build under your own brand, with your own database, ramp partners and licences. This page is the short version of the notes in the repository.
1. Try it locally in three commands
Node 22 and pnpm 10. No database, wallet or API key is needed; the API runs on an embedded Postgres with sample data.
git clone https://github.com/sera-cx/sera-payroll.git && cd sera-payroll pnpm install pnpm demo # API in demo mode on http://localhost:4000/v1 pnpm --filter @sera-payroll/web dev # web app on http://localhost:5173
To run the web app exactly like this site, with no API at all: VITE_MOCK_API=1 pnpm --filter @sera-payroll/web dev.
2. What the server build adds
- Postgres with migrations, or the embedded PGlite for a single-box demo.
- Sessions and roles enforced on the server: magic links, Sign-In with Ethereum, API keys, client scoping.
- The payout worker: screening, swap, wallet or off-ramp delivery, idempotent retries, and payslip anchoring on chain.
- Webhooks signed with HMAC, a delivery log, and PDF payslips.
- Real wallet signing: EIP-712 approval of a pay run, Sera.cx swap intents signed in the browser, the batched disbursement from the treasury wallet.
- Email through SMTP; without it the outbox is the log, as on this site.
Everything outside the core sits behind an interface: SwapProvider (Sera.cx), RampAdapter, ScreeningProvider, StatutoryPlugin, Notifier and ChainAdapter. Mock implementations ship for each.
3. Deploy the server build
The API is one container. It runs migrations on start, serves /v1, runs the worker and delivers webhooks. The web app is a static build that you point at the API with VITE_API_BASE.
One click on Render
The blueprint at render.yaml creates the API, a Postgres database and the static site. Render asks for three URLs during setup; the deployment guide lists them and what to check after the first deploy.
Any Docker host
docker build -f apps/api/Dockerfile -t sera-payroll-api . docker run -p 4000:4000 \ -e DATABASE_URL=postgres://... -e SESSION_SECRET=$(openssl rand -hex 32) \ -e WEB_ORIGIN=https://payroll.example.com -e COOKIE_SAME_SITE=none \ sera-payroll-api
A Fly.io config is in deploy/fly.toml. CI builds and boots the image on every push, so the Dockerfile stays honest.
The environment that matters
| Variable | What to set |
|---|---|
DEMO_MODE | true for a public demo with sample users and the permanent banner; false for an operator. |
WEB_ORIGIN, COOKIE_SAME_SITE | The web app's origin. none when the web app is on a different site from the API, which then needs HTTPS. |
CHAIN, RPC_URL | sepolia or ethereum with a JSON-RPC endpoint; mock keeps everything off chain. |
PAYROLL_DISBURSER_ADDRESS, PAYSLIP_REGISTRY_ADDRESS | The contracts below on Sepolia, or your own deployment. |
OPERATOR_SIGNER_PRIVATE_KEY | Signs payslip roots and pays gas to anchor them. Never holds funds. |
SWAP_PROVIDER, SERA_API_KEY, SERA_API_SECRET | sera with keys from Sera.cx (testnet base https://api-testnet.sera.cx/api/v1); sample plays back fixed rates. |
SMTP_URL, SMTP_FROM | Real email. Unset keeps the outbox only. |
The full list with defaults is in apps/api/.env.example.
4. Contracts
Two settlement contracts and two demo stablecoins are deployed on Sepolia, verified on Sourcify. Point the API at them, or deploy your own with Foundry.
| Contract | Address on Sepolia |
|---|---|
| PayrollDisburser | 0x874DE1F483Dd5C053E51cf9e9dAc161452050b85 |
| PayslipRegistry | 0x1E187E50cE8F4F8ec7124DCE7FD1Abf37938449D |
| tUSDT faucet | 0x608007F91A38D43E964939C2F29c4397349F71AC |
| tMYRT faucet | 0xCc0054146fBE0105655633ce4ebb2930acc3FFC1 |
cd contracts && forge test forge script script/Deploy.s.sol:Deploy --rpc-url $SEPOLIA_RPC_URL --broadcast --skip-simulation --slow
--skip-simulation matters: current Sepolia charges several times Foundry's local estimate for contract creation. Only the two settlement contracts are meant for mainnet. Treasury wallets must approve the disburser on each stablecoin they pay with; the web app offers that step before signing.
5. Before paying anyone for real
- A database and an email provider. Postgres is wired; implement
Notifierfor your email service. - Ramp partner adapters. One
RampAdapterper licensed partner and currency: deposit instructions, funds confirmation, hosted identity checks, bank payout creation and status. - Screening. A real
ScreeningProvider, run before every payout. The default is a pattern rule with an optional Chainalysis check. - Statutory plug-ins. One
StatutoryPluginper country with real rules. The sample is a flat percentage. - Accounts and SSO. Connect your identity provider and existing user base.
- Licences. Moving salaries and handling fiat are regulated. You and your ramp partners carry them.
- Your brand. Replace the
[YOUR PAYROLL BRAND]placeholders. "Settlement by Sera.cx" stays as the only Sera.cx mark, and any public demo keeps the permanent demo banner.
Where the notes are
- README: what it is, quick start, rules the code keeps, risks.
- docs/DEPLOY.md: GitHub Pages demo, contracts, full stack on Render, Fly or Docker, search engine notes.
- docs/BUILD_NOTES.md: the design, in eighteen sections. Also summarised on the build notes page.
- docs/API.md: the HTTP contract, webhooks and API keys.
- docs/ON_CHAIN_PAYSLIP.md: the payslip commitment scheme behind the verifier.
- contracts/script/README.md: deploying and verifying the contracts.
MIT licensed. github.com/sera-cx/sera-payroll