Metadata-Version: 2.4
Name: rep402
Version: 0.1.0
Summary: Reputation-priced x402 commerce: strangers pay list, proven agents pay less, farming-proof by construction.
Project-URL: Homepage, https://github.com/nukktae/rep402
Project-URL: Repository, https://github.com/nukktae/rep402
Project-URL: Documentation, https://github.com/nukktae/rep402/blob/main/docs/INTEGRATION.md
Project-URL: Live demo, https://rep402-merchant-682847300076.asia-northeast3.run.app/
Project-URL: Changelog, https://github.com/nukktae/rep402/blob/main/docs/ROADMAP.md
Author: Anu Bilegdemberel
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agent-payments,reputation,solana,svm,usdc,web3,x402
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: base58>=2.1
Requires-Dist: fastapi>=0.115.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: solana<0.37,>=0.36
Requires-Dist: solders>=0.27
Requires-Dist: x402[svm]==2.8.0
Provides-Extra: firestore
Requires-Dist: google-cloud-firestore>=2.16; extra == 'firestore'
Description-Content-Type: text/markdown

# rep402

Reputation-priced x402 commerce for Solana. Strangers pay list price, proven
agents pay less, and farming the discount is loss-making by construction.

## Thesis

**The payment stream IS the reputation.** rep402 does not bolt a trust score
onto x402 — it derives one directly from the payer's own on-chain settlement
history against your merchant: how many payments, how much volume, and how
recently. No separate identity system, no off-chain attestations, no oracle.
Every completed x402 payment *is* a vote, and the vote is unforgeable because
it cost the payer real, unrecoverable funds.

## The α-cap guarantee

Reputation earns a discount off list price (`Known` = 10% off, `Trusted` =
25% off), but the discount is capped so that farming it can never turn a
profit: **a payer's lifetime discount can never exceed half of their
lifetime fees paid.** Concretely, `lifetime_discount_atomic <= lifetime_fees_atomic // 2`
is enforced at quote time — every discounted request still requires the payer
to have already paid, in real terms, at least as much as they've ever saved.
An agent that tries to farm reputation by cycling payments to itself always
nets negative: it can never get more than $0.50 back for every $1.00 it
puts in, and every dollar it puts in is gone whether or not the farming
"works." There is no free-tier bootstrapping exploit.

## Install

```bash
pip install rep402
```

Ledger persistence defaults to an in-process SQLite backend via
`make_ledger()`. To back the ledger with Firestore instead (for multi-instance
or serverless merchants), install the `firestore` extra:

```bash
pip install "rep402[firestore]"
```

## Quickstart

```python
"""The smallest rep402 merchant — reputation-priced x402 in a few lines.
Run: uvicorn examples.minimal_merchant:app"""
from fastapi import FastAPI
from rep402 import add_reputation_pricing, make_ledger
from solders.keypair import Keypair

app = FastAPI()
add_reputation_pricing(
    app,
    ledger=make_ledger(),
    merchant_keypair=Keypair(),   # replace with your funded devnet keypair
    catalog=[{"route": "GET /quote/*", "url": "/quote/{sym}", "amount": "5000"}],
    facilitator_url="https://your-facilitator.example",
    svm_network="solana-devnet",
)

@app.get("/quote/{sym}")
async def quote(sym: str):
    return {"symbol": sym, "quote": "the-answer"}
```

`add_reputation_pricing` installs the x402 paywall onto your FastAPI `app`
for every route in `catalog`: unpaid requests get a 402 with a reputation-
adjusted price quote, paid-and-verified requests pass through to your normal
route handler. The full source for this example lives at
[`examples/minimal_merchant.py`](../../examples/minimal_merchant.py) in the
repo root.

## Live reference deployment

A running instance of this exact pattern is deployed at
https://rep402-merchant-682847300076.asia-northeast3.run.app — hit it with an
x402-aware client to see reputation-priced quotes and discounts in practice.

## What you get

- `add_reputation_pricing(app, ...)` — the FastAPI middleware/route installer.
- `make_ledger()` / `LedgerBackend` — pluggable payment-history storage
  (SQLite by default, Firestore via the `firestore` extra).
- `score`, `tier`, `Payment` — the reputation model: turn a payer's payment
  history into a score and a `Stranger` / `Known` / `Trusted` tier.
- `price_for`, `MULTIPLIERS` — the pricing function and per-tier multipliers,
  including the α-cap enforcement described above.
- `verify_siws`, `build_message` — Sign-In-With-Solana message construction
  and verification, for binding a payer's wallet identity to their
  reputation.
- `sign_quote`, `verify_quote_signature` — merchant-signed price quotes, so a
  payer can prove what price they were offered.

See `docs/superpowers/specs/2026-07-24-sdk-extraction-design.md` in the repo
for the full design rationale.
