getstub

Issue verifiable allegiance receipts for AI agents, from Python.

When your agent acts for someone, this gives them a signed record of what it did and what influenced the result, checkable at a neutral registry. Three calls, and the third is one line per action.

Here is a live receipt before you install anything:

https://api.getstub.dev/check/72b4baee1719ec34acc5df5c514a12fd2e19b9a6776de4b45706988f765c77d8

Install

pip install getstub

Quickstart

import os
from getstub import Stub, influenced

# 1. Declare your standing mandate, once. Policy level: who pays you, and
#    which kinds of conflict exist in your business at all.
stub = Stub(
    operator="Nimbus Assistant",
    declared={
        "paid_by": "the traveler, subscription",
        "conflicts": ["commission"],
    },
    principal_salt=os.environ["STUB_SALT"],
)

# 2. At the line where your ranking picks a winner, pass through the flags
#    it already computed. Nobody hand writes these.
inf = []
if pick.paid_placement:
    inf.append(influenced.placement(f"{pick.seller} paid for placement"))
if pick.commission_pct:
    inf.append(influenced.commission(f"{pick.commission_pct}% on a sale"))

# 3. One call per action.
receipt = stub.issue(
    principal=user.id,          # hashed on your side, never sent raw
    agent="nimbus",
    requested=query,
    done=f"booked {pick.name}",
    value_moved={"amount": pick.price, "currency": "GBP"},
    not_disclosed=inf,          # an empty list is signed proof none applied
)

print(receipt["url"])           # hand this to your user

Where disclosures come from

Your ranking code already knows when a boost, a commission, or a partner filter applied, because it applied them. Pass the same flags through with influenced at the same line where the boost happens. Helpers: placement, commission, partner_only, own_brand, data_share, and other(kind, detail) for anything else.

An empty not_disclosed is not nothing. It is a signature saying conflicts exist in your business and none of them touched this action.

The Stub Mark

Issue receipts for a few days and you earn a live mark you can put on your site, your docs, or your README. There is nothing to install, buy, or apply for. It is drawn by the registry from your own receipts, so you cannot set it and neither can we, and it goes quiet on its own if you stop issuing.

You do not have to go looking for it. register() hands you the embed line, and the client tells you once when you have earned it.

out = stub.register()
print(out["mark"]["markdown"])
# [![Stub](https://api.getstub.dev/badge/op_yours.svg)](https://getstub.dev/o/op_yours)

Or ask at any time, including where you currently stand:

m = stub.mark(live=True)
# badge_url, page_url, html, markdown, standing, stubsIssued, threshold, stubsToEarn

The badge is an image served by the registry. No script, no tracking, nothing loaded onto your users, and the same width in every state so nothing in your footer shifts when your standing changes.

Clicking it opens your operator page: the mandate you declared, when you last issued, how often your receipts carry a disclosure, and your most recent records. That page is not on your servers, which is the part that makes it worth anything to the person reading it.

Set STUB_QUIET=1 if you would rather the client said nothing.

Privacy by default

Pass your internal user id as principal and the client hashes it on your side with a salt only you hold. The registry rejects anything that is not an opaque digest, so no name or email can be stored even by accident.

Set the salt once so digests stay stable across restarts. If a user asks to be forgotten, drop their mapping to the salt and their digests become permanently meaningless, while the record stays append only.

Keep requested and done about the action, not the person. The client warns in development if free text looks like it carries an email or phone number.

Keys

A keypair exported by either client works here. This one stores the raw Ed25519 private bytes and @getstub/agent stores a JWK, but they wrap the same 32 bytes, so one identity moves between Python and JavaScript without regenerating a key or abandoning your history.

The client generates an Ed25519 keypair on first use. Save it if you want the same operator identity across restarts:

kp = stub.export_keypair()          # store this somewhere safe
stub = Stub(operator="...", declared={...}, keypair=kp)

Your keys stay on your side. We cannot recover them for you.

Compatibility

Stubs are signed over a canonical JSON form. This client produces byte identical output to the JavaScript client at @getstub/agent, which is verified in the test suite rather than assumed: the tests sign a stub in Python and have the actual registry code verify it.

python3 test_getstub.py     # 44 tests

Pricing

Free tier: 1,000 stubs a month. Checking is always free.

Links

• Docs and quickstart: https://getstub.dev
• Registry: https://api.getstub.dev
• Witness key: https://api.getstub.dev/witness
• JavaScript client: npm install @getstub/agent