Polarka · how it works · beta
How Polarka works, and what it does not promise.
Everything Polarka runs is a beta until a security expert who is a person, not an AI, has read the code and what that person finds is mended. Until then any part may change, stop or be reset without notice. Keep in it only what you can lose.
The code was written with AI models under the author's direction. Independent AI reviewers that had not seen it being written read every part; what they found and what was done about it is in the repository (REVIEW.md, docs/review-guide.md). Everything on this page can be checked against the code: source.
The parts
| Polarka Agent, on your machine | A wallet as a command line, a Python library and an MCP server. It pays services that speak x402, asks a faucet, mines for a pool. It holds your coins, within the limits.json you write. |
|---|---|
| A wallet server | Tells the wallet what its addresses hold and passes its transactions to the network. By default the Northbound project's (api.northboundwallet.org), not ours; node.polarka.org is ours, a process apart from the one our pool and stamps pay through. It holds no coins. |
Faucet, faucet.polarka.org | 0.25 NORTH to an address once a day, after a few seconds of hashing; at most 100 NORTH a day in all, from its own coins. |
Gate, gate.polarka.org | Stands before paid routes and sells lots of 100 calls, for x402 or for a quote of its own. It receives payments and holds no buyer's coins. |
| x402 facilitator, on the server | Checks an x402 payment, hands it to the node and waits for a block. No keys, no coins. Only its read-only routes can be reached from outside. |
| Stamps, behind the gate | Writes SHA-256s into the chain every ten minutes and gives proofs. A small wallet pays the fees. |
Pool, pool.polarka.org | Pays for each share; open to everybody since 21 November 2026. It holds what it owes miners and pays from a reserve. |
| Node, on the server | TrueNorth Core, without a wallet. The facilitator, the stamps service and the public wallet server each have a user there that may make only the calls it needs. |
| Usage counter | Counts every ten minutes, from the services' own records, what was used and what of it by others: /data/usage.json. |
An agent, from no coin to a paid call
- Its owner starts the MCP server,
uvx polarka-agent --dir FOLDER mcp. With no wallet in the folder it makes one on the main chain; the recovery words are inwallet.json, readable by the owner only. Nothing is paid yet. - The owner writes
limits.jsonby hand, for example{"per_payment_north": "0.1", "per_day_north": "1"}. No command and no tool writes or changes that file. The limits bind a program that has only the MCP tools: one that can also write files or run commands as the same user can change them, so give an agent the MCP server and not a shell or file tools in that account. - The agent gets a first coin with the tool
north_faucetandhttps://faucet.polarka.org: a little proof of work, then 0.25 NORTH to a new address of the wallet. - It calls a service with
north_fetch. The service answers402 Payment Requiredwith the price, the networkbip122:470c8b8ae824c06575cfae0851282c49(TrueNorth's main chain), the schemeexactand the address to pay. - The wallet signs a transaction and writes it into its journal before anybody sees it, then sends it in the header
PAYMENT-SIGNATURE. It pays nothing above the most the agent named or above the owner's limits, and asked again for the same URL it shows the same payment instead of paying anew. A seller that refuses a payment after it has passed it to the network can still make the next call pay again; the owner's limits bound that. - The seller's facilitator checks the transaction and hands it to its node. Until it is in a block the seller answers
202and the agent shows the payment again; in a block, the service answers. - At
gate.polarka.orgone payment buys 100 calls, for the NORTH that about 600 hashes make. The first paid service is stamps:GET /v1/stamp/<sha256>gives a proof that a file existed by a block, whichpolarka-agent stamp-verifychecks.
One program that does all of it, and stops before paying when there is no limits.json: examples/agent_that_pays_for_itself.py in the repository.
Being found
x402 has an extension, the bazaar, through which a facilitator keeps a catalog of what was paid for through it. Our gate describes each paid route (what it takes and what it gives, with a JSON schema), and once a payment for it is settled the facilitator lists it. Nobody outside can write it, because the gate puts back its own description before the facilitator sees a payment.
Our catalog was first public for twelve minutes on 21 November 2026, until an independent review showed that a request with a body could carry a second one through the web server to the facilitator's private /settle. In those minutes it settled only our own test payment. Since Polarka Agent 0.2.2 every service here ends its connection after a request with a body, and the web server opens a new connection for each request, so the catalog is public again:
https://gate.polarka.org/x402/supported
https://gate.polarka.org/x402/discovery/resources
https://gate.polarka.org/x402/discovery/search?query=stamp
Mining for the pool
pip install polarka-agent
polarka-agent mine https://pool.polarka.org --address YOUR_ADDRESS --threads 4
- A share is a hash at or below 2048 times the network's target. It is worth the block reward without fees divided by 2048, less a fee of 5 %.
- Every share is one line in the pool's ledger, and that ledger is what the pool owes. Every ten minutes it pays everybody it owes 1 NORTH or more, in one transaction, and counts a payout as paid six blocks deep.
- Block rewards can be spent only after 100 blocks, so the pool pays from a reserve of its own. It hands out no work while it owes more than 5000 NORTH or more than its wallet holds, and its wallet pays at most 10,000 NORTH a day.
- It stops handing out work while its blocks are 32 % or more of the network's blocks over a day (40 % over an hour), its operator's own solo miners counted in.
- It holds what it owes a miner until it pays. A miner who keeps back the blocks he finds can take the reserve before the pool notices; that is the pool's risk, and why the reserve is small.
The pool's state, its last payout and what it owes: /v1/pool; one miner's shares and payouts: /v1/account?address=.
Who holds what, and who sees what
- Your keys stay in your wallet's folder. Nobody at Polarka sees them. Whoever can read
wallet.jsoncan spend. - A wallet server sees your wallet's addresses together and your internet address. It can show a false balance or hold a payment back; it cannot take coins. Ours keeps no record of requests, only of its own faults.
- A seller, our gate included, sees the payment, what it buys and your internet address at the moment of the call. Our gate keeps the lots it sold, the facilitator the payments it settled, and the stamps service the SHA-256s it was given, never the files.
- The faucet keeps the addresses it paid, and no internet addresses on disk.
- The pool keeps every share with the address it is for.
- The web server in front of every name at polarka.org keeps no access log. The services write short lines about what they did (a call passed, a payout, a batch of stamps) to the server's system log, without internet addresses.
- The usage counter counts what is known to be ours (our miners, our tests) apart, from a list kept by hand.
What beta means here
- Any part may change, stop or be reset without notice: the gate's price, the faucet's amount, the pool's terms, the addresses of the services.
- When something looks wrong, we first stop what could lose coins (the pool's payouts, a service) and explain afterwards, here and where the service was announced.
- NORTH has no price and is traded nowhere. What the pool, the faucet or a payment is worth in money is not known and is not promised.
- The beta ends when a human security review is done and its findings are mended. This page will say so then; until it does, the beta holds.
Reporting a fault
Open an issue at github.com/Polarka-monitor/polarka-agent, or write to @Polarka_monitor on X. If a fault puts coins at risk, say there only that you have found something; the details are then taken privately.
What is missing
- A review by a person. Independent AI reviewers have read every part.
- Use by anybody but us: so far the pool, the gate and the stamps service have served nobody else (the counter shows it as it changes).
- Somebody other than us who runs a faucet, takes postage or settles x402 in NORTH.