Stub recipes

Working reference integrations for Stub, the allegiance receipt registry for AI agents.

Each recipe is a runnable agent with Stub wired in at the line where the ranking picks a winner. Clone one, run it, read the receipt it produces.

Every recipe here is a reference and a simulation. No real merchants, no real money, no real users. Nobody is running these in production, and each README says so. The point is to show exactly where a receipt belongs in code you recognise.

The recipes

Every recipe runs against the live registry and issues real receipts, under an operator id you choose. The free tier is 1,000 stubs a month, so trying all six costs nothing. There is no offline mode and no mock registry: the only way to issue a stub is to issue one.

The badge above

These recipes are exercised against the live registry every day, and the badge is drawn from the receipts that run produces. It is not a build status: it says the reference agents ranked their catalogues, disclosed what influenced the result, and issued signed records anyone can open. Click it to read them.

If it ever goes quiet, the recipes stopped working and this repo is telling you so before you clone it.

Start here

If you are new to this, read tool-loop first. It is the smallest one and it carries the lesson the others repeat: the model does nothing wrong, the ranking decided.

cd tool-loop
npm install
export STUB_OPERATOR_ID=op_yourname_toolloop
npm run demo

Pick an operator id that is yours. The first run registers it and saves your keypair to .stub-keys.json, which is gitignored. Every run after that uses the same identity.

The demo prints the ranking your code produced, with the reason beside each item, and then a receipt link anyone can open.

When you are ready to deploy

The recipes generate a fresh keypair each run, which is right for reading and wrong for production. PRODUCTION.md covers what changes: persisting your identity, where the receipt belongs, what never goes in the free text, and the mistakes we made taking our own agent live.

What a stub is

When your agent acts for someone, it issues a small signed record: who asked, what was done, what money moved, and what commercial influence applied. The person served checks it at a neutral registry, not on your servers and not on ours.

Here is a live one before you install anything:

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

The integration, in full

import { Stub, influenced } from '@getstub/agent';

const stub = new Stub({
  operator: 'Your Agent',
  declared: {
    paid_by: 'the user, subscription',
    conflicts: ['commission'],
  },
});

// at the line where your ranker picks a winner:
const inf = [];
if (pick.paid_placement) inf.push(influenced.placement(pick.seller));
if (pick.commission_pct) inf.push(influenced.commission(pick.commission_pct + '%'));

const receipt = await stub.issue({
  principal: user.id,        // hashed on your side, never sent raw
  agent: 'your-agent',
  requested: query,
  done: `booked ${pick.name}`,
  value_moved: { amount: pick.price, currency: 'USD' },
  not_disclosed: inf,        // an empty array is signed proof none applied
});

Python is the same shape:

from getstub import Stub, influenced

Two things that keep coming up

Nobody hand writes disclosures. Your ranking code already knows when a commission or a placement fee shaped a result, because it applied it. The receipt reads the same flags at the same line. It scales the way your ranking scales.

An empty disclosure is not nothing. It is a signature saying conflicts exist in your business and none of them touched this action. That is worth more than silence, and it is why honest operators have something to gain here.

Install

npm install @getstub/agent
pip install getstub

Both clients sign over the same canonical form, verified rather than assumed: the Python test suite signs a stub and has the registry code verify it.

Free tier

1,000 stubs a month. Checking is free forever, because charging the person being served to verify would defeat the point.

Links

• getstub.dev
• Registry: https://api.getstub.dev
• Witness key: https://api.getstub.dev/witness
• Directory of operators: https://api.getstub.dev/directory

Copyright Stub 2026