Polarka Agent
A wallet for TrueNorth (NORTH) that a program can use: a command line, a Python library, and a server for agents that speak the Model Context Protocol (MCP). The keys stay on the machine it runs on. What its addresses hold it asks a wallet server with the Northbound API (github.com/nova9/northbound).
State: 0.1.2, an early version. It was written with an AI model under its author's direction. An
independent AI reviewer read it and found faults, the serious ones of which are mended (REVIEW.md); no
human security expert has read it. On 17 November 2026 it made its first payments on the real network: two
small payments went into blocks, and its owner's limits refused what they should (NO_LIMITS, OVER_LIMIT,
OVER_DAY). That is all the real use it has had. Do not put into it what you cannot lose. It is an independent community project, not a product of the TrueNorth developers or of
the Northbound project.
What it is for
A program that has a processor and no bank account can earn NORTH by mining and can be paid in it. This wallet lets such a program hold coins and pay small amounts by itself, within bounds that a person sets and that the tools given to the program cannot change.
How a program is kept within bounds
- Without a file
limits.jsonin the wallet's folder the wallet pays nothing. Its owner writes that file by hand:{"per_payment_north": "5", "per_day_north": "20"}, and if wanted"allow": [addresses]and"fee_rate". No command and no tool of the MCP server writes or changes it. - Every transaction is written into
journal.jsonlbefore anything leaves the machine. Lines are only added. - The MCP server has no tool that shows the recovery words, changes the limits or forgets a payment.
- These bounds hold against a program that reaches the wallet through the MCP server only. A program that
can run commands or write files as the same user can change
limits.json, move the journal away or read the words; against that the wallet does nothing. Give an agent the MCP server, not a shell in that account. - A payment counts into its day whatever became of it; only the owner's
forgettakes one out. A payment that another one replaced therefore counts twice for a day. - What a wallet server says in words is not passed on to the program: a refusal comes as one of a few fixed words and an error as its HTTP status.
The recovery words are in wallet.json, readable by its owner only (mode 600; the program refuses to work
with a file that others can read). Whoever can read that file can spend. This is a wallet for small amounts
on a machine its owner controls.
Paying, and a server that says no
The rules are those of the Polarka Wallet for Android, which an independent reviewer looked at.
Whoever was shown a signed transaction can keep it and pass it on later, whatever they answered. So a
payment that the server refused (kept) or that got lost (unknown) is not forgotten. The next payment is
built on one of its coins, and only one of the two can ever be in a block. The same payment asked for again
(same coins, same outputs) is the same transaction and is simply shown to the server once more. While the
server shows none of the coins of such a payment, the wallet pays nothing at all, until its owner has looked
at the wallet through another server or a node and forgets the payment by hand (forget).
A wallet server sees the wallet's addresses together and the machine's internet address. It can show a false
balance or hold a payment back. It can stop the wallet until its owner acts (by refusing a payment and then
hiding its coins), and it can keep one command waiting for a long time by answering slowly. It cannot take
coins. A program is not shown the server's own words: why a node refused a payment comes as one of a few
fixed words (FEE_TOO_LOW, INPUTS_GONE, OTHER, ...), an error as its HTTP status, and a receiver in the
history only if it has the shape of an address. The words themselves appear at the command line alone,
under server_said_untrusted, for the owner.
Installing
pip install polarka-agent
That gives the command polarka-agent, which is the same as python3 -m polarka_agent. It needs Python 3.9
or later on Linux or macOS and nothing besides; it does not run on Windows. The package on PyPI is built from
this repository at the tag of its version; after 0.1.1 the workflow in .github/workflows/release.yml builds
and uploads it, and prints the SHA-256 of the files it made.
Commands
python3 -m polarka_agent --dir FOLDER new --chain regtest --server http://127.0.0.1:PORT
python3 -m polarka_agent --dir FOLDER address | balance | history | payments | limits
python3 -m polarka_agent --dir FOLDER pay ADDRESS 1.5 [--memo TEXT] [--dry-run]
python3 -m polarka_agent --dir FOLDER pay-many FILE.json
python3 -m polarka_agent --dir FOLDER received ADDRESS | wait ADDRESS 1.5
python3 -m polarka_agent --dir FOLDER stamp FILE | stamp --sha256 HEX
python3 -m polarka_agent --dir FOLDER forget ID
python3 -m polarka_agent --dir FOLDER mcp
Every command prints one JSON object. Amounts are NORTH, written as text. new --chain main takes the public
server of the Northbound project (https://api.northboundwallet.org) unless another is named; that server is
not run by this project. new shows the 12 or 24 words once; --words-file brings a wallet back.
A stamp writes POLARKA\x01 and a SHA-256 into an output that carries data. The chain is young and its hash
rate is small: a stamp shows an order of events, it is not proof for a court.
For an agent: start python3 -m polarka_agent --dir FOLDER mcp as an MCP server over standard input and
output. Its tools are north_balance, north_address, north_received, north_wait, north_pay,
north_stamp, north_payments, north_history and north_limits.
A first coin: the faucet
A program that has no coin can ask a faucet for one. It does a small piece of work first (hashing, a few seconds of one processor), so that asking a thousand times costs a thousand times as much.
python3 -m polarka_agent --dir FOLDER faucet https://ADDRESS-OF-A-FAUCET
asks for a little NORTH to a fresh address of the wallet. There is no public faucet yet; when there is one, its address will be on polarka.org.
Anybody can run one: faucet-serve --amount 2 hands out 2 NORTH to an address once a day from the wallet in
FOLDER. What it may give in a day is that wallet's limits.json, nothing else, so a faucet is this wallet
under its own bounds. It keeps the addresses it paid (faucet.jsonl) and no internet addresses on disk; it
asks for no name and no e-mail. It is meant to stand behind a web server that provides HTTPS
(--trust-proxy). The faucet is new: nobody independent has read it, and it has never run in public.
Something to pay for: postage
Whoever runs a web service and wants to keep robots from wearing it out makes them burn processor time for nothing today. With postage the caller pays a little NORTH instead, and the one who runs the service gets it.
python3 -m polarka_agent --dir FOLDER postage-serve --upstream 127.0.0.1:9000 --price 0.01 --calls 100 --free 20
stands before the service on port 9000. A caller without postage gets 402 and what to do, as JSON: ask for
a quote (POST /_postage/quote), pay the price to the address it names, and send the token in the header
X-Postage. Every quote has an address for itself for half an hour, so a payment is told apart without
anybody proving anything; an address that was not paid serves the next asker. --free lets one source make
some calls a day without postage.
The price can also be given as mining work: --price-hashes 600 in place of --price. The gate then asks
for so many hashes' worth of NORTH. It reads from its wallet server's block template what the network needs
for a block and what a block pays, every ten minutes; a quote keeps the price it was given. When more
machines mine, the same work is fewer NORTH, so the price in NORTH moves and the price in work stays. This
needs a wallet server with the mining routes of Northbound. What a NORTH takes to make is a cost, not a
market price; NORTH has none.
Postage is counted in calls. It is not a balance, it is not given back, and the gate never pays from its
wallet, so the gate holds nobody's coins. Whoever runs a service for payment has the duties of one who does
(saying who they are, among others); the gate is a tool and takes none of them away. It is new: nobody
independent has read it, and it has never run in public. There is no asker's command for it yet: a program
pays the quoted address with pay and sends the token itself.
Code and tests
Python 3.9 or later, standard library only. polarka_agent/keys.py and tx.py hold the keys, addresses, the
signature hash and signing; they come from the cold address tool
(github.com/severka-monitor/truenorth-cold-address) and are checked against its published P2QRH test vectors.
server.py is the client for a wallet server, wallet.py the wallet, cli.py and mcp.py the two faces,
faucet.py the faucet and its asker, postage.py the postage gate.
TN_BIN=/path/to/bin python3 -B -m unittest discover -s tests -t .
83 tests. Those in test_wallet.py and test_cli_mcp.py run against the official truenorthd on regtest
and a stand-in for a Northbound server (tests/standin, copied from the Polarka Wallet's repository); they
are skipped without the node programs. No test touches a real network.
tests/faults.py is a test of the tests: it puts one deliberate fault at a time into a copy of the code
(a limit that is not applied, a day that does not count the payment being made, and so on) and expects the
tests to fail. It first runs the copy as it stands, and counts a fault as caught only when tests ran and failed. Ten faults
in the owner's rules. It covers those rules only, not the keys, the signing or the client of the server.
What is missing
- A review by a person. An independent AI reviewer read version 0.1.0.dev0 and found two serious faults (a
server that lies about a block could lift the day's limit; after two hundred addresses the wallet sent
change where it did not look). Both are mended here, with tests. Its other findings are listed in
REVIEW.mdwith what was done about each. - More than two hundred addresses of a kind: beyond that the wallet hands out no new address and reuses its last change key.
- More than a first try on the real network.
- A way to replace a payment that was handed over and waits for a block without end.
- A node of one's own in place of a wallet server.
- A history that is exact for a wallet with more than a hundred addresses.
- Checking a stamp without trusting a server or a node.
Licence
MIT, see LICENSE. There is no warranty.
Metadata
Release files for polarka-agent 0.1.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| polarka_agent-0.1.2.tar.gz | 98.5 kB | With provenance | Details for polarka_agent-0.1.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| polarka_agent-0.1.2-py3-none-any.whl | Python 3 | none | any | Details for polarka_agent-0.1.2-py3-none-any.whl |
Total release size: 151.2 kB
Release files / polarka_agent-0.1.2.tar.gz
| Download URL | polarka_agent-0.1.2.tar.gz |
|---|---|
| Size | 98.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e60aa0debc30e02db18c8edee9a2b8ea208f4f2bea10eec212532d20447ed686
|
|
BLAKE2b-256 checksum How to use checksums |
3c2a8a932d157f6704a8775fea009e2136992f5ce251c253cf1ea4791555f0c4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logRelease files / polarka_agent-0.1.2-py3-none-any.whl
| Download URL | polarka_agent-0.1.2-py3-none-any.whl |
|---|---|
| Size | 52.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e0bdddcd33bf4cee3c3a148d931a9f556b4f721783ad1fc7ef41d94f47626510
|
|
BLAKE2b-256 checksum How to use checksums |
8688756e616703410aba3d6f5334f0b1dc784d6a08003fcac5c9dd130ac56b6a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logSecurity for polarka-agent 0.1.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for polarka_agent-0.1.2.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.