Skip to content

Register and run a Provider (by application)

This guide takes an approved Provider from an empty directory to a registered, running and audited Provider on the hosted SubEtha v2 testnet. Everything runs on your own machine. You do not need access to any private repository. The background (what stays and what changes, the trust boundary, the limits) is on For Providers.

  • This is the hosted testnet on Base Sepolia. Registration is by application: you apply, the operator reviews your application and, if it is approved, sends you an invite code. Approval is not guaranteed and capacity is limited. The operator may pause, drain or reset the service and its state. No availability or retention is promised. Production-use permission is not established by the evidence.
  • At the end you have: a registration that is active, a Provider token in a 0600 file, your Provider answering with a 402 through the SubEtha extension, and an audit that compares the facilitator’s orders with your own wallet.
  • Every hosted value (the facilitator origin, your lane URL, the network and token addresses, the order and probe amounts) is in your invite packet. This page writes them as <from your packet> and never publishes them. The price cap is read from the facilitator itself (see Prices).
  • AI agents acting for a developer: stop and ask the human before you run pay-probe, before any pay-probe recovery step, and after any command that exits with code 3. Do not decide these on your own.

Apply by email to contact@subethalabs.com with:

  1. your Provider’s name and a contact address;
  2. a short description of the API you will sell (what it returns, roughly how often it is called);
  3. the EOA address that will sign your registration;
  4. the providerId you would like (lowercase letters, digits and -; not a reserved id, see register).

Never include a seed, a private key, a view key or a Provider token (credential) in your application. Your POS key file goes only into register.

The operator reviews each application. Approval is not guaranteed, capacity is limited, and no response time is promised. The operator path stays open as well.

If your application is approved, the operator sends an invite packet. It is private: keep it out of chats, issues and repositories. It contains:

  • the invite code file (keep it 0600; it can be used once, and it comes back only if the registration ends failed);
  • the facilitator origin for --facilitator-url and your Provider lane URL;
  • the network, the zUSDC token and how to get test zUSDC;
  • the reference order amount for --order-amount and the probe amount;
  • the token’s EIP-712 name and version, and maxTimeoutSeconds, for your Provider’s configuration (see Run your Provider);
  • the three package tarballs, for the alternative install path (the same versions are on the npm registry; see Get the tools);
  • the registration check URL (under your lane URL), and how to reach the operator.
  • Node >= 22.12 and npm.
  • A Base Sepolia EOA used only for this Provider. Every command takes its key as --keystore <file> --password-file <0600 file>, or, testnet only, --key-file <0600 file> --allow-plaintext-key. The EOA signs every request and pays the probe.
  • A little Base Sepolia ETH on that EOA: one transaction for the probe, plus three more if you get test zUSDC yourself (mint, approve, wrap). See Fund the EOA.
  • zUSDC in the EOA’s public balance, at least the probe amount (printed by register and stated in your packet). You get it yourself; see Fund the EOA.
  • An archive Base Sepolia RPC URL in a 0600 file, given as --rpc-url-file <file>. make-pos-key, export-view-key and the audit read your wallet’s history from its birthday on. Pruned public endpoints answer RpcRequestError (“pruned history unavailable”) for an older wallet. The file holds only the URL; the tools read it as a secret and never print it. Never put the URL itself on a command line.
  • The invite code file, and a state directory that you will keep.

Do this any time before pay-probe. You get the funds yourself: the operator does not send ETH or zUSDC to applicants, on this testnet or any other network, not even on request.

  1. Base Sepolia ETH. About 0.00001 ETH is ample for the four transactions at recent fees (on 2026-11-18 they cost about 0.000002 ETH in all). A public faucet may not serve a fresh EOA (Base Sepolia ETH says why); then send a little ETH from another testnet wallet of your own.
  2. Test zUSDC. Get test USDC (mint it to the EOA), approve the official zUSDC contract to spend it, and wrap it with that contract. The test USDC is the zERC20 testnet’s own token (“Dummy USD Coin”), not Circle’s USDC: its mint is the faucet, and USDC from Circle’s faucet does not work here. The copy-paste commands are in Mint, approve, wrap; the two contract addresses are in your packet. An AMOUNT a little above the probe amount is enough. Wrapping puts it in the EOA’s public balance, which is what pay-probe spends.

Get the tools (verify before you run anything)

Section titled “Get the tools (verify before you run anything)”

The Provider tools (subetha-provider-wallet, subetha-provider-audit) and the Provider extension are three packages. They contain SubEtha’s own compiled code only; their third-party dependencies are installed from the npm registry under their own licences. Install them from the npm registry at exactly the versions below (the main path), or from the tarballs in your invite packet (the alternative). Both give the same bytes.

Each package must match the integrity value listed here. This list is the reference, not the copy in your packet; install only the versions listed:

File Package Integrity (SRI)
subetha-provider-tools-0.1.0.tgz @subetha/provider-tools 0.1.0 sha512-xlyUDi+/nTGW+WZyjcDt7fdS06XVQnBMBZlS9I/9FvmmZV4eoUfC4gcnHWQOmLtDejXN9TGy1t0TSmUNTWVfVg==
subetha-provider-0.2.0.tgz @subetha/provider 0.2.0 sha512-BBf6Cw15lBslM9VgeM/CXVakGaaOryopfuHCrtr0uch0HYaOr6Vyth2D8p6wnYxbBePv+yrPoI1/Db+3TuTAVQ==
subetha-x402-scheme-0.2.0.tgz @subetha/x402-scheme 0.2.0 sha512-6t0sv1dXrunZuRCHMtNVdid0YNNiBL+qABDawBFqzLl7/sfxDHFVs6GZF5u1bYW5iIJdKHMs7rHl72DBQLaRvw==

These three versions carry no npm provenance attestation. npm audit signatures verifies their registry signatures, and the integrity values in this list identify the exact bytes.

  1. Make a new, empty project directory. Do not install anything globally.

  2. Install the three versions exactly, without lifecycle scripts:

    Terminal window
    npm init -y
    npm install --save-exact --ignore-scripts @subetha/provider-tools@0.1.0 @subetha/provider@0.2.0 @subetha/x402-scheme@0.2.0
  3. Check the integrity of node_modules/@subetha/provider-tools, node_modules/@subetha/provider and node_modules/@subetha/x402-scheme in package-lock.json before anything runs:

    Terminal window
    grep -A4 -E '"node_modules/@subetha/(provider-tools|provider|x402-scheme)": \{' package-lock.json | grep -E 'node_modules|integrity'

    Each integrity must equal the value listed above for that package, character for character. Stop on any difference, remove the directory, and do not run anything from it.

  4. Check the registry signatures and run the tools:

    Terminal window
    npm audit signatures
    npx subetha-provider-wallet help
  1. Make a new, empty project directory and copy the three tarballs into it. Do not install anything globally.

  2. Check each tarball before anything runs. This prints its integrity value:

    Terminal window
    for f in subetha-provider-tools-0.1.0.tgz subetha-provider-0.2.0.tgz subetha-x402-scheme-0.2.0.tgz; do
    printf '%s sha512-%s\n' "$f" "$(openssl dgst -sha512 -binary "$f" | openssl base64 -A)"
    done

    Each value must equal the one listed above for that file, character for character. Stop on any difference, and do not install that tarball.

  3. Write this package.json in the directory. The overrides entry makes every package use the local scheme tarball, so nothing of SubEtha’s is fetched from the registry:

    {
    "private": true,
    "type": "module",
    "dependencies": {
    "@subetha/provider-tools": "file:subetha-provider-tools-0.1.0.tgz",
    "@subetha/provider": "file:subetha-provider-0.2.0.tgz",
    "@subetha/x402-scheme": "file:subetha-x402-scheme-0.2.0.tgz"
    },
    "overrides": { "@subetha/x402-scheme": "$@subetha/x402-scheme" }
    }
  4. Install without lifecycle scripts, then check the registry signatures of the third-party dependencies:

    Terminal window
    npm install --ignore-scripts
    npm audit signatures
    npx subetha-provider-wallet help

    npm audit signatures covers registry packages only. On this path the three local tarballs are covered by step 2 and nothing else.

npx subetha-provider-wallet help covers registration and the probe recovery only; make-pos-key, export-view-key, status and withdraw are described on this page.

npm may report vulnerabilities after these installs and the one in Run your Provider. They are advisories for third-party dependencies, not for SubEtha-authored code; on 2026-11-17 they concerned zod (through the @x402/* packages), qs (through express) and underscore (in the Provider tools’ dependency tree). This page makes no statement about their effect on your deployment; review npm audit for your own environment.

Licence: SubEtha-authored code is Apache-2.0. The zERC20 SDKs and their dependencies come from the npm registry under their own terms. No commercial-use right, public-hosting right or official status is granted for any zERC20 component.

Every registration command also takes:

  • --facilitator-url <from your packet>;
  • --state-dir <dir> (default .provider-wallet). Keep this directory. It holds your signed requests, the probe journal and registration.meta.json, which pins the facilitator’s deployment id. A different deployment is refused there; use another --state-dir for it;
  • the key options from What you need.

Give --rpc-url-file <file> to subetha-provider-wallet and to the audit, too. The commands below leave these common flags out to stay readable; add them to every command.

Terminal window
npx subetha-provider-wallet make-pos-key --out pos.key

It can take tens of seconds. The POS key lets the facilitator derive the per-order addresses that your wallet can see. It cannot spend, and it holds no seed and no view key. The file goes only into register.

Terminal window
npx subetha-provider-wallet register --id <id> --pos-key-file pos.key --order-amount <from your packet> --invite-file invite.code --credential-out provider.token
  • Your Provider token is written to provider.token (0600) before anything is sent. The signed request is saved to <state-dir>/registrations/<digest>.json, without the POS key, before it is sent too.
  • It prints regId, status: "pending", the probe (address, amount, payFrom), expiresAt, requestFile and credentialFile. Keep the regId and the probe address. Keep every probe address: the audit needs them.
  • A 202 (still being set up) is re-sent every 5 s, 12 times. If it is still not done, or the answer was lost (exit 3), or a re-send was refused: keep provider.token and run npx subetha-provider-wallet register --resume <requestFile>. It returns the stored result and never sends the POS key again. Do not register again under a new id.
  • A 202 at the end is normal. Setting up a new lane takes the facilitator about 1.5 minutes, and it normally ends as pending or failed within a few minutes. register then exits 0 with "status": "reserving" and a next line. Wait a minute and run register --resume <requestFile> again, until status is pending (go on to pay-probe) or failed. If it is still reserving 5 minutes after the first register, stop and ask the operator. On failed the invite can be used again, but that POS key cannot (duplicate-pos-key): make a new one with make-pos-key and register again.
  • --order-amount is the reference price you declare at registration, in the token’s smallest unit. It must be at most the facilitator’s price cap (see Prices); above it the request is refused with 400 price-above-cap (exit 1) before anything is reserved, and the refusal does not use one of your 3 new registrations per hour. It does not fix the prices you charge.
  • Ids are lowercase letters, digits and -. sample, test2, op, admin, operator, facilitator, x402, subetha, each of them followed by -…, and anything starting with reg- are reserved (409 id-reserved). One live registration per EOA (409 eoa-limit).
  • Each IP may start 3 new registrations per hour (429, with Retry-After). A --resume does not count. A refused attempt can count: see the next section. Check the id, the invite file and your EOA before you send.
  • 403 closed: registration is not open at the moment. It is normally answered after the request’s format, signature, expiry and POS key are checked, and before the invite. Then your invite was not looked at, and the refusal does not use one of your 3 new registrations per hour. If the operator closes registration while your request is being processed, the same answer comes from a second check after the invite check, and that request uses one of your 3. In both cases your invite is not used up. Wait, or ask the operator; the operator path stays open.
  • 403 invite-invalid: registration is open, but the request reached the invite check without a valid invite (none, unknown, already used or revoked). The id and POS-key checks come first. This refusal does use one of your 3, as do id-reserved, eoa-limit, tenants-full and a registration that ends failed. Ask for a new invite; do not retry with the same code.

Both are refusals (exit 1).

Agents: stop and ask the human before this step.

Terminal window
npx subetha-provider-wallet pay-probe --reg <regId> --to <probe address>

It pays the probe amount, the smallest unit of zUSDC, exactly once, from the EOA’s public balance. It checks first that the registration is pending and that --to is its probe address. It journals the attempt in <state-dir>/probe-journal.jsonl before sending, never pays twice, and prints the txHash.

Why the probe. It proves that your POS key’s lane really receives into your wallet before any buyer pays you. The facilitator cannot judge that from the keys alone. The probe is paid from your registered EOA to show that you run a working wallet, at a small cost per identity; this is not Sybil resistance.

There is no SubEtha mainnet service today. If such a service opens beyond this testnet, funding works as here: you pay the gas and public zUSDC on that network yourself, and the operator sends nothing. Use a wallet only for your Provider there: the probe transfer is public and shows that its EOA registered as a SubEtha Provider. How to get zUSDC on that network is not verified and is not described here.

Once the probe transaction is mined, run:

Terminal window
npx subetha-provider-wallet activate --reg <regId> --tx <txHash>

It checks the payment in your own wallet first and only then signs Activate. The facilitator accepts it once the transaction is deep enough (probeConfirmations in its GET /register/info answer, 3 blocks by default).

  • 409 receipt-too-shallow (with confirmations and required): the transaction is not deep enough yet. Wait a few blocks (a few seconds on Base Sepolia) and run it again.
  • Activate before expiresAt (24 h after registering). After that the registration is expired: the id is free again and the invite is used up. Ask for a new invite.

All of these are signed by your EOA:

  • npx subetha-provider-wallet status --reg <regId> --credential-file provider.token: the registration; with the file, credentialCurrent says whether it holds the current token. (status with no --reg or --id is the wallet status.)
  • npx subetha-provider-wallet rotate-credential --reg <regId> --credential-out <new file>: a new token. The old one stops at once. This also works when you have lost the token.
  • npx subetha-provider-wallet remove --reg <regId>: only once all your orders are finished (409 not-terminal). An order behind an unpaid 402 is not finished when its quote expires: the facilitator watches it for a late payment for a configured number of days after the expiry, and it is finished only once that period is over and the chain has settled past it. So even one unpaid order keeps remove refused for days. Your Provider keeps working meanwhile; to stop new orders sooner, ask the operator to suspend it.
Code Meaning What to do
0 done —
1 refused (the JSON error says why) fix the cause; nothing was paid by this run
2 usage error: nothing was sent or written fix the command
3 outcome unknown: the request may have been applied follow the printed command (register --resume …, status --reg … --credential-file <new file>)

After an exit 3, never register again under a new id. Agents: stop and ask the human.

rotate-credential exits 3, or fails after writing the new file: keep both files, then run npx subetha-provider-wallet status --reg <regId> --credential-file <new file> to see which one is current.

pay-probe stops with “the probe journal is locked” or “was started and its result is not recorded”: the transfer may or may not have been sent. Never run it again blindly. npx subetha-provider-wallet help says the same. Agents: stop and ask the human.

First make sure no pay-probe is running. Then look on a Base Sepolia block explorer for a transfer of the probe amount from your EOA to the probe address.

  • Found: append this line to <state-dir>/probe-journal.jsonl, with the attempt of the started line:

    {"event":"probe-pay-sent","attempt":"<attempt of the started line>","regId":"<regId>","txHash":"<hash>"}

    Then remove <state-dir>/probe-journal.jsonl.lock and run activate --reg <regId> --tx <hash>.

  • Not found: the outcome stays unknown. Leave the journal and the lock as they are. A missing transfer, an empty mempool or an unchanged nonce does not prove that nothing was sent (another RPC endpoint may hold the transaction), and nothing makes it expire. Look again from time to time; if the transfer appears, do the step above before expiresAt. Never end the started line yourself without the transfer.

To pay a probe again, in this order:

  1. Keep the old --state-dir and its journal.
  2. Make sure the old registration has been released: status --reg <regId> says expired or removed, or the operator confirms it. 24 h passing is not enough by itself.
  3. Get a new invite. The old one stays used up.
  4. Only then register again with a different --state-dir and a new POS key (make-pos-key).
  5. Keep watching the old probe address: the old transfer can still arrive, and the audit needs it.

Or ask the operator.

Keep the whole state directory in every case: the signed requests, the probe journal and its lock, and registration.meta.json.

@subetha/provider and @subetha/x402-scheme are already installed and verified by Get the tools. Add the official x402 packages, Express and viem from the npm registry in the same directory, at exactly these versions (the extension checks at start that every @x402/* package is one copy of 2.28.0):

Terminal window
npm install --save-exact --ignore-scripts @x402/core@2.28.0 @x402/evm@2.28.0 @x402/express@2.28.0 @x402/extensions@2.28.0 express@4.22.2 viem@2.57.7

Mount the extension around your existing handler, as on For Providers. This complete example has one paid route, GET /v1/hello; replace existingHandler with yours. It is plain JavaScript (ESM), so mark the package as a module first:

Terminal window
npm pkg set type=module

Save this as app.mjs:

// app.mjs — a complete Provider with one paid route. Run: node app.mjs
import express from "express";
import { createSubetha, FileStoreAdapter, SubethaStore } from "@subetha/provider/x402";
const env = (name) => {
const value = process.env[name];
if (!value) throw new Error(`set ${name} (see the table below)`);
return value;
};
const port = Number(process.env.PORT ?? "8581");
const facilitatorUrl = env("FACILITATOR_URL"); // your lane URL
const providerToken = env("PROVIDER_TOKEN"); // the contents of provider.token
const store = new SubethaStore(FileStoreAdapter.open(".subetha-store"), { windowMs: 86_400_000, nonceTtlMs: 15 * 60_000 });
const subetha = createSubetha({
store,
facilitator: { url: facilitatorUrl, providerToken },
origin: env("ORIGIN"), // the origin buyers use
internalOrigin: `http://127.0.0.1:${port}`, // this process, on loopback
recoveryBase: "/subetha", // recovery routes live under this path
network: env("NETWORK"),
asset: env("ASSET"),
token: { name: env("TOKEN_NAME"), version: env("TOKEN_VERSION") },
maxTimeoutSeconds: Number(env("MAX_TIMEOUT_SECONDS")),
}, { "GET /v1/hello": { amount: env("PRICE"), fixed: true, mimeType: "application/json" } });
// your existing handler, unchanged
const existingHandler = (_req, res) => res.json({ hello: "world" });
const app = express();
app.use(express.json());
app.use(subetha.guard); // 1. before the x402 middleware
app.use(subetha.paymentMiddleware); // 2. the official middleware, built by the helper
app.use(subetha.observer); // 3. after x402, before the handlers
app.use(subetha.handlers); // 4. recovery
app.get("/v1/hello", existingHandler);
const server = app.listen(port, "127.0.0.1", () => {
subetha.start() // refuses to serve on any failed check
.then(() => console.log(`listening on http://127.0.0.1:${port}`))
.catch((e) => { console.error(`startup refused: ${e.message}`); server.close(); process.exit(1); });
});

Set the configuration in your process environment, for example in a .env file (0600; keep it out of repositories, since it holds your Provider token), and run node --env-file=.env app.mjs. Values are not published here:

Name Value
FACILITATOR_URL your Provider lane URL, from your packet
PROVIDER_TOKEN the contents of provider.token from register; it reaches only your own orders
ORIGIN your public origin, see below
NETWORK, ASSET from your packet
TOKEN_NAME, TOKEN_VERSION the token’s EIP-712 name and version, from your packet
MAX_TIMEOUT_SECONDS from your packet
PRICE your price for GET /v1/hello, in the token’s smallest unit (see Prices)
PORT optional; the local port, 8581 if unset

The three addresses the extension needs:

Option What it is Example
origin The public origin buyers use. The resource URLs and the recovery URLs are built from it. It must be https, except a loopback address (http://127.0.0.1:<port>) for a local trial. https://api.example.com
internalOrigin This process on a loopback address. The extension calls it to run your handler for an order that was paid but not delivered in its own request. It must be a loopback address that reaches this process. http://127.0.0.1:8581
recoveryBase A path you choose for the recovery routes, where the wallet that paid gets the response again (signed in with SIWX, no second payment). A recovery URL is <origin><recoveryBase>/orders/<orderId>. /subetha

start() refuses to serve when a check fails, for example an origin or FACILITATOR_URL that is not https outside loopback, an internalOrigin that is not a loopback address, or an @x402/* package that is not one copy of 2.28.0. The example then prints startup refused: … and exits.

Each route’s amount is your price for that route, in the token’s smallest unit; see Prices.

You choose your prices in your own Provider, per route, with no facilitator call: each route’s amount in the extension’s route table, in the token’s smallest unit, for example { "GET <route A>": { amount: "<price A>" }, "GET <route B>": { amount: "<price B>" } }. Routes need not have the same price, and a price need not equal your --order-amount.

  • The cap. The facilitator accepts any amount from 1 up to its price cap, maxOrderAmount in its GET /register/info answer (the endpoint is under the facilitator origin from your packet). Read the current value there; this page does not publish it. Above the cap, creating the order answers 403 amount not allowed by the run policy with maxOrderAmount, so that route cannot be sold.
  • Each order keeps the amount it was created with.
  • Changing a route’s price takes a restart of your Provider. Offers already made at the old price and not yet paid can then no longer be paid: the payment is refused before settlement, so no funds move, and the buyer has to start a fresh purchase (a new request without a payment header) to get the new price. Payments already settled are delivered as before.

To check the registration, call the registration check URL from your packet with your token:

Terminal window
curl -H "Authorization: Bearer $(cat provider.token)" "<registration check URL from your packet>"

It answers 200 with your own orders; 401 means a wrong token and 404 an unknown id. The facilitator’s supported answer is the same for any id, registered or not, so it only shows that the facilitator is reachable; it is not a check of your registration.

Export your view key (it can see, it cannot spend) and audit regularly:

Terminal window
npx subetha-provider-wallet export-view-key --out view.key
npx subetha-provider-audit --facilitator-url <your lane URL> --token-file provider.token --view-key-file view.key --birthday <ISO date> --probe <each probe address> --rpc-url-file <archive RPC file>

--birthday is your wallet’s birthday, an ISO date such as 2026-01-01T00:00:00.000Z, as printed by export-view-key (and by status without --reg). The first audit needs it; later audits use the stored one and refuse a different value. The birthday is set when the state directory is first used, 2 hours before that time as a margin, so it is earlier than when you made the wallet.

The audit exits 1 when the facilitator’s orders and your wallet disagree. Your Provider trusts the payTo the facilitator hands out; the audit is how you check it afterwards. Give it every probe address you have ever had.

Withdraw with npx subetha-provider-wallet withdraw <to> <amount> --max-fee <max fee>: one public withdrawal, journaled, never repeated automatically.

Never send anyone your seed, your EOA key or a view key. The POS key file goes only into register.

Reviewing applications and issuing invite codes. Also suspending or resuming a Provider, POS key rotation, late payments, uncertain orders, and a Provider whose routes are quarantined. If your first generation is retired while you are still pending, activate answers 409 probe-path-closed; the operator then finishes the registration with a new POS key and a new probe. Ask the operator in these cases.

  • Availability or retention. The operator may pause, drain or reset the service and its state.
  • Privacy beyond what zERC20 and the testnet provide. Your address and the payment are public on Base Sepolia; see Who sees what.
  • Delivery after a chain reorg of the payment. Delivery follows the mined receipt, not chain finality.
  • Any value for test assets.

A mined payment and body delivery do not establish merchant-side mint or spendability; see Limits.

“Fund the EOA” added on 2026-11-18 after a live self-funded registration (the test USDC’s on-chain name read that day); the same day the operator’s testnet ETH fallback was removed (owner decision: the operator sends no funds to applicants). Funding and probe text revised on 2026-11-17 after the owner kept the probe payment design (the applicant pays from the registered EOA). Reviewed 2026-11-17 against the product repository at e972064 and re-read on 2026-11-18 against 68e061b; the package versions and integrity values are from the Provider kit release record, built and reproduced at 1176fc0 and unchanged at e972064. On 2026-11-17 the npm registry’s integrity for each of the three versions equalled the list, and a fresh install from the registry was checked as in Get the tools. The price cap was also checked against the hosted testnet’s GET /register/info. Evidence is the product repository’s own records; this site ran no registration and made no payment for this page. On 2026-11-17 the example in Run your Provider was run against the product repository’s simulated facilitator (startup checks passed, the paid route answered 402); the explanations of origin, internalOrigin, recoveryBase, the birthday and activate follow the product source at e972064.