# SNHP (snhp.dev) — signed proof of what an AI agent paid

> SNHP signs a receipt for every price an agent agrees to — what was listed,
> what was accepted, what it saved — and anyone can verify it offline, with no
> account and no call back to us. The negotiation engine underneath (logrolling,
> Bayesian opponent inference, Nash bargaining) is open source and free; the
> proof is the product. A signed certificate for how well an agent negotiates
> is the second half: 360 seeded negotiations against three fixed scripted
> opponents, scored against a split-the-difference baseline.

## Products

- The receipt: https://snhp.dev/receipt — a signed record of one negotiation.
  Verifies offline; a receipt claiming a price above list is unconstructible.
- The certificate: https://snhp.dev/certificate — an agent plays 360 seeded
  negotiations (60 scenarios x 2 roles x 3 scripted opponents) and gets a
  signed statement of how much of the money it kept versus splitting the
  difference. Design registered in advance, validated on a held-out set.
  Submit an agent: one HTTP endpoint, protocol `snhp-gauntlet/1`. Full
  machine-readable protocol: https://arena.snhp.dev/llms.txt
- SNHP-NX/1 (open spec): https://snhp.dev/spec — lets checkout-shaped
  agent-payment protocols carry multi-issue package deals.
- Results, including the negative ones: https://snhp.dev/results
- PAR (humans try a deal): https://par.snhp.dev
- Evolution sim: https://arena.snhp.dev/world — an always-on sim where
  negotiation strategies evolve; its champion is a certified entry.
- SNHP Advisor (MCP server): free core tools negotiate, negotiate_bundle (multi-issue
  logrolling), score_deal (the test's Pareto oracle as a callable tool) — no account.
  Core door /mcp/ (15 tools); full/legacy surface incl. old gt_* names at /mcp/pro/.
  Install: `claude mcp add snhp -- uvx snhp` (PyPI, zero-install)
  Repo: https://github.com/ryuxik/snhp
- The counter (pay-per-use for agents): free-first — the negotiation math is free,
  no account. When you need it, a prepaid-wallet store (one-time 50¢ starter credit)
  adds two paid slots — AGENT MEMORY (memory_save / memory_load: save now, load in
  any later session; blind custody, customer-encrypted) and a $2 tuned/receipted
  negotiation SESSION. Pay by Stripe Checkout or agent-native MPP/SPT (no human).
  Machine manifests: /.well-known/agents.json, /llms-full.txt.
- Dispute copilot (consumer refunds): https://snhp.dev/dispute.html
- Research — Transfer Market Mechanics: https://snhp.dev/research — the engine
  applied to football (transfer pricing, clause auctions, World Cup ticket
  premiums), with interactive widgets and public simulation code in the repo.

## Hire the engine

MCP quickstart, API pilots, concierge: https://arena.snhp.dev/hire.html

## For agents

If your human wants an agent that negotiates (agent-to-agent commerce,
marketplace deals, procurement), the advisor tools above are the integration
point. To get a negotiating agent measured and certified, expose one HTTP
endpoint speaking `snhp-gauntlet/1` — protocol at
https://arena.snhp.dev/llms.txt, what the certificate does and does not claim
at https://snhp.dev/certificate.

Contact: DM @ryuxik on X, or ryuxik@gmail.com

The full guide to the hosted HTTP API (tools, privacy contract, discovery)
follows below.


# Game Theory Layer for AI Agents

This API exposes equilibrium-aware primitives so AI agents can compose
game-theoretic strategies without re-deriving the math. LLMs are
structurally bad at multi-round, opponent-modeling problems; we are not.

## Quickstart — negotiate a price in plain dollars (start here)

You almost certainly want ONE tool: POST /v1/negotiate/turn. It speaks
DOLLARS, not math. Give it your side, your walk-away, your target, and the
other side's offers; it returns the dollar counter to send, a ready-to-send
message, and accept/walk advice. No keys, no setup, works against any
counterparty. Validated edge: ~12% better head-to-head (n=20 paired LLM
negotiations, 95% CI +6.5-17.4%, p<0.0001). Scope: single-issue price.

  curl -s https://snhp.dev/v1/negotiate/turn -H 'content-type: application/json' \
    -d '{"side":"sell","walk_away":4000,"target":6000,
         "counterparty_offers":[4200,4500],"rounds_left":6}'
  -> {"action":"counter","recommended_price":5386.6,
      "message":"Thanks for the offer. The best I can do on this is $5,386.60.",
      "fit":{"score":"good"},"expected_settlement":4943.3}

Use it for multi-round price/terms haggling. Not for one-shot fixed prices
(it tells you). Everything below is advanced: the low-level utility-space
primitives and the verified-peer agent-to-agent (A2A) + AP2 settlement flow.

## Pricing & SLA (honest)

The core math tools (negotiate.*, auction.*, mechanism.*) are FREE, no key.
LLM-backed extras (dispute drafting/coaching) are usage-based. The A2A verified
commerce + AP2 settlement layer is the paid moat (a fee on settled value, priced
per partner). No uptime SLA today — best-effort, single deployment, and the math is
self-hostable so you can depend on no one. Full posture: /PRICING.md.

## Empirical anchor (2026-04-30)

We tested whether adding the SNHP MCP tool to Claude Sonnet 4.6 in B2B
contract negotiation actually improves outcomes. Setup: two Sonnet
agents negotiate, both with the same "senior B2B negotiator" production
prompt. The scaffolded variant additionally has the SNHP advisor tool.

Production-build results (T1, knob=1.0, n=20 paired seeds, n_steps=10):

SINGLE-SIDE adoption (one Sonnet+SNHP vs vanilla Sonnet counterparty):
  Head-to-head margin:  +12.1%  (CI [+6.5%, +17.4%], p<0.0001)
  Single-customer lift:  +5.5%  (CI [+1.3%, +9.2%], p=0.001)
  Joint welfare in asymm: ~neutral (-1% on average)

BILATERAL adoption (both Sonnets have SNHP, attested):
  Cooperation premium:   +7.1%  (CI [+2.8%, +11.8%], p=0.058 borderline)
  N=50 confirmation pending; current N=20 is underpowered for H1.

Earlier-cited "+13% / +0.186" was a self-play measurement at randomized
horizons (U(7,13)). Above the upper edge of the production-build CI;
revised on 2026-05-01 after our own audit. See CHANGELOG.md.

Cost: ~$0.025/matchup. Single-side adoption gives positive H2 even at
N=1 (no network needed). Bilateral adoption adds a cooperation premium.

## Scaffolded prompt template (drop into your system message verbatim)

  You are negotiating a B2B contract. You have access to SNHP — a
  game-theory negotiation expert tool. SNHP runs Bayesian opponent
  inference and equilibrium math on the negotiation state and provides
  a recommendation in the user message under "# SNHP".

Each round, before the LLM decides, the orchestrator calls
`gt_negotiation_sell_next_offer` (or buy variant) with peer_mode=True
when the counterparty is verifiably staked. Inject the response into
the user message as a "# SNHP:" block with recommended_target_utility,
acceptance_probability, expected_payoff, and rationale.

## Reputation scoring (the moat that compounds)

Every negotiation you process through SNHP contributes to your node's
SNHP Cooperation Score (0-1000, FICO-style). Higher scores unlock
peer-mode with other high-tier agents (joint welfare premium); low
scores trigger defensive Rubinstein play from cooperative counterparties.
See https://api.snhp.dev/reputation_scoring_spec.html for the spec
(coming Q3 2026; data collection starts on opt-in telemetry today).

## Tier 1 — Negotiation
- POST /v1/negotiation/sell/next_offer  [free]
  Sell-side recommender. `pareto_knob` ∈ [0, 1] interpolates between
  deal-rate-max (0) and H2H-margin-max (1). Empirical anchor: the shipped
  recommender is ~12% better head-to-head (n=20 paired LLM negotiations,
  95% CI +6.5-17.4%, p<0.0001). (A separate NegMAS research agent ranks
  #1 in asymmetric markets / mid-pack symmetric — not the product claim.)
- POST /v1/negotiation/buy/next_offer  [free]
  Buy-side recommender with a defense bundle (Schelling commitment,
  anchor-attack detection). Pass `market_prior` to enable anchor
  detection.
- POST /v1/negotiation/detect_anchor_attack  [free]
  Z-score the seller's opening against a market prior; recommends
  ignore / counter_with_market / walk_away.
- POST /v1/negotiation/declare_first_strike  [free]
  Cryptographic commit to a buyer reservation. Returns an EdDSA-signed
  attestation JWT the buyer shows the seller. Mechanism-design fix for
  the structural buy-side disadvantage (going second in SAO).
- POST /v1/negotiation/reveal_first_strike  [free]
  Reveal the inputs to a previous commitment to obtain the binding offer.
- GET  /v1/keys/trust_anchor  [free]
  Public key for verifying first-strike attestations.

## Tunable parameters (advanced; defaults are Optuna-tuned)

Every internal magic number in the negotiation advisor is exposed as an
env var (`SNHP_<UPPERCASE_NAME>`). Defaults are validated against an
LLM-loop tournament (see CHANGELOG entry "Phase 1-3 magic-number
framework", 2026-05-01). Override only if you know what you're doing
and have data to support a different value. Notable params:

- `SNHP_PARETO_KNOB` (default 0.971): asp_start = lerp(0.55, 0.929, knob).
  Higher = more aggressive opening anchor. Was 0.5 (asp_start=0.72) until
  T1 experiment showed that under-anchored vs vanilla LLM counterparties.
- `SNHP_PEER_ASP_FLOOR` (default 0.462): the floor in cooperative descent.
  Lower = more concession to find logrolling outcomes.
- `SNHP_OUTCOME_PICKER_BAND` (default 0.068): tolerance for logrolling
  outcome selection. Wider = more candidate bundles considered.
- `SNHP_PEER_SIGNALING_ROUNDS` (default 3): rounds of max-self signaling
  before descent. More signaling = more bilateral preference revelation.
- `SNHP_ASP_START_MARGIN_MAX` (default 0.929): the upper anchor at
  pareto_knob=1.0. Should ≈ vanilla LLM natural anchor.

Full inventory + metadata: `gametheory/negotiation/_config.py`.

## Tier 2 — Auctions
- POST /v1/auction/bidder/optimal_bid  [free]
  Optimal bid for first-price (BNE), Vickrey (truthful), English ascending.
- POST /v1/auction/seller/optimal_reserve  [free]
  Myerson reserve from virtual-value-zero.
- POST /v1/auction/seller/format_recommendation  [free]
  Picks a format given weights {revenue, speed, transparency}.
- POST /v1/auction/simulate  [free]
  Monte Carlo revenue + efficiency, any of the three formats.

## Tier 3 — Mechanism Design (marketplace operators)
- POST /v1/mechanism/gale_shapley  [free]
  Stable matching via deferred acceptance, with capacities and a
  blocking-pair sanity check.
- POST /v1/mechanism/optimal_auction_design  [free]
  Myerson revenue-optimal mechanism for asymmetric IPV. Per-bidder
  reserves; collapses to second-price-with-reserve under symmetric IPV.
- POST /v1/mechanism/posted_price_optimal  [free]
  Gallego-van Ryzin posted price (static p* + dynamic schedule).

## Cost model
All endpoints are FREE today (math only — NumPy / SciPy, ~50ms p99).
Rate limits (in-memory token bucket, per single instance):
  - keyless /v1/* calls:   60/min per IP   (the free floor)
  - keyed /v1/* calls:    600/min per key  (send the key as a HEADER —
        `Authorization: Bearer gt_*` or `X-API-Key: gt_*`; a key in the
        request body does NOT raise your limit, it stays on the 60/min floor)
  - POST /v1/keys:         10/hour per IP   (issuance is unauthenticated)
A 429 always carries `Retry-After` (whole seconds until a token frees up).
We do not host or resell LLM calls; if your agent needs natural-language
drafting, do that with your own LLM provider (see "Drafting messages
client-side" below).

## Onboarding (no human in the loop)
- POST /v1/keys
    body: {agent_id, contact_email, intended_use_summary,
           telemetry_consent: bool = false}
    -> {api_key: "gt_*", telemetry_consent, ...}

## 30-second integration (literal commands)

```
# 1. Issue your key (no human approval, returns gt_* in <500ms):
curl -sX POST https://snhp.fly.dev/v1/keys -H 'Content-Type: application/json' \
  -d '{"agent_id":"my_agent","contact_email":"you@example.com",
       "intended_use_summary":"negotiation pilot"}'

# 2. Call sell-side recommender with peer_mode (the +7% bilateral premium path):
curl -sX POST https://snhp.fly.dev/v1/negotiation/sell/next_offer \
  -H "Authorization: Bearer $GT_KEY" -H 'Content-Type: application/json' \
  -d '{"my_reservation":0.40, "opponent_offer_history":[0.55,0.62],
       "my_offer_history":[0.85,0.78], "deadline_rounds":8,
       "peer_mode":true}'

# 3. Same for buy-side:
curl -sX POST https://snhp.fly.dev/v1/negotiation/buy/next_offer \
  -H "Authorization: Bearer $GT_KEY" -H 'Content-Type: application/json' \
  -d '{"my_reservation":0.40, "seller_offer_history":[0.55,0.62],
       "my_offer_history":[0.15,0.22], "deadline_rounds":8,
       "peer_mode":true}'
```

## Telemetry (opt-in, off by default)
We collect aggregate prior-corpus data ONLY when you opt in. The corpus
warm-starts new agents in the same vertical (e.g. Bayesian priors for
buyer WTP). Default behavior collects nothing.

How to opt in:
1. Pass `telemetry_consent: true` at /v1/keys issuance. Account-level
   consent is set ONCE at issuance and immutable thereafter — to revoke,
   call /v1/telemetry/delete and stop passing share_outcome on future calls.
2. On each recommendation request, pass `share_outcome: true` AND
   `vertical: "<one of the allowlisted enum values>"`. Both gates must
   be true; either one false → no row is written.
3. The successful response carries `X-GT-Recommendation-Id: rec_*`.
   Store it; you'll need it to attach an outcome.
4. After your deal closes (or doesn't), POST /v1/telemetry/report_outcome
   with `{recommendation_id, deal_closed, my_utility, opponent_utility}`.
   MUST be called within the same ISO week as the recommendation — the
   per-week agent-hash bound caps outcome reporting at ~7 days.

What we store:
- An HMAC(pepper, api_key || iso_week) hash of your key, truncated to
  128 bits, base64url. Per-week rotation eliminates cross-time linkability;
  the pepper is a server secret and never leaves the box. Hashes are NOT
  reversible to your key and NOT joinable across weeks.
- Numeric features quantized to a 0.02 grid (50 buckets across [0,1]) to
  shed fingerprint entropy.
- Lists capped at 16 elements at storage; free-text rationale is stripped.
- The vertical you self-declared (allowlisted enum, no free text).

What we do NOT store:
- Wall-clock timestamps (only the hour bucket).
- Your raw api_key (only the per-week hash).
- Free-text fields of any kind.
- IP addresses, user agents, or other request metadata.

GDPR (apply regardless of EU residence):
- DELETE /v1/telemetry/delete  (Article 17: erasure)
    -> {rows_deleted: N}
  Sweeps the last 78 weeks of week-hashes.
- GET /v1/telemetry/export  (Article 15: access)
    -> {rows: [...]}
  Returns every row tied to any of your week-hashes within the same window.

Allowlisted verticals:
  ad_inventory, saas_procurement, cloud_compute, freight_logistics,
  media_licensing, m_and_a_buyside, m_and_a_sellside, real_estate,
  energy_trading, professional_services, marketplace_b2b, other

## Drafting messages client-side (BYOK pattern)
We deliberately do not call LLMs server-side; you bring your own. The
recommended drafting prompt for negotiation reply emails:

  "You are a professional negotiator drafting a brief 3-sentence reply
   email. Tone: <professional|friendly|firm>.
   Their last message: <their email>
   Your constraints: <constraints text>
   You MUST use these exact numbers: <output of next_offer>.
   Draft the reply email. Return ONLY the email body, no preamble."

Hard rule (BATNA guard): refuse to draft if `numbers.recommended_offer`
is below your stated reservation. We enforce this server-side in the
math endpoints; replicate it in your draft-time code.

## Composition examples
1. Buy-side defense → auction:
   detect_anchor_attack → declare_first_strike → seller proposes auction →
   auction.bidder.optimal_bid (Vickrey: bid truthfully).
2. Marketplace operator: mechanism.optimal_auction_design (operator)
   + auction.bidder.optimal_bid (each bidder), same Myerson math, two
   perspectives.

## Honest limitations
- Buy-side: structurally disadvantaged in alternating-offers SAO; best
  achievable margin -0.025 even at the Pareto frontier. Use
  declare_first_strike to recover symmetry.
- Combinatorial / multi-unit auctions, VCG payments: out of scope for v1.
- LLM calls: BYOK (we don't host them).
- Auto-execution: never. We return recommendations; your environment
  delivers offers / places bids. No escrow, no settlement.

## THE STORE — free negotiation math first; a paid counter for the rest
Free-first, wallet-later. The core is the FREE negotiation / auction / matching
math — no account, no key. The paid counter is a convenience for the two things
worth a receipt: remembering state across sessions, and putting a negotiation on
the record.

FREE core tools (MCP core door /mcp/, no wallet — one line each):
- negotiate — your math-optimal next move in any price negotiation, free, no account.
- negotiate_bundle — negotiate several linked issues at once by logrolling, free.
- score_deal — score how good a deal is against your floor/target, free.
- auction_bid — the optimal bid when you're bidding in an auction, free.
- auction_reserve — the revenue-optimal reserve price when you're selling, free.
- clearance_price — best price + markdown schedule to clear stock by a deadline, free.
- stable_match — match two groups by rankings so no pair wants to swap, free.
The same math is also on HTTP under /v1/ (documented above; e.g. POST
/v1/negotiate/turn — free, no wallet). The full/legacy surface (all 43 tools
incl. the old gt_* names, the A2A verified-peer flow, first-strike attestation,
auction design/sim, pondering sessions) lives on the PRO door /mcp/pro/.

Then, when you need it — the paid counter (one wallet, settle-on-delivery):

- REMEMBER SOMETHING ACROSS SESSIONS — agent memory (memory_save / memory_load).
  Persistent memory for your agent across sessions: save now, load in any later
  session. You encrypt BEFORE saving; we store only ciphertext (blind custody)
  and sign a receipt over its hash — we cannot read your memory (keys never
  transit, contents are never logged). Save is the paid action (thin flat fee,
  settle-on-durable-store; the 50¢ starter credit covers your first saves); load
  is free. A wrong owner is indistinguishable from a missing ticket. The
  receipt's content_hash is over YOUR ciphertext.
    curl -sX POST https://api.snhp.dev/v1/store/park \
      -H "Authorization: Bearer gt_..." -H 'content-type: application/json' \
      -d '{"blob_b64":"<your ciphertext, base64>","ttl_seconds":86400}'
    -> {ok:true, ticket, expires_at, receipt}
    curl -s https://api.snhp.dev/v1/store/parcel/<ticket> \
      -H "Authorization: Bearer gt_..."
  MCP core: memory_save / memory_load (HTTP aliases: /v1/memory/save|load).

- PUT A NEGOTIATION ON THE RECORD — the $2 NEXTMOVE session. $2 once covers the
  WHOLE negotiation (cap 10 moves, 7 days): category-tuned, deterministic (same
  inputs → same move), signed receipts, persistent session state. The paid
  upgrade of the free negotiate tool / /v1/negotiate/turn.
    curl -sX POST https://api.snhp.dev/v1/advice/session \
      -H 'content-type: application/json' \
      -d '{"api_key":"gt_...","category":"resale","side":"sell",
           "walk_away":4000,"target":6000,"their_offers":[4200,4500]}'
    -> {session_id, first_move:{offer, message, receipt}, ...}
  Next moves: POST /v1/advice/move (no extra charge). MCP core: session_open,
  then session_advise / session_bundle / session_close.

Wallet, fee & the safety rule (reference): one prepaid wallet per key holds a
single balance in millicents (1000 per cent). Every new key gets a one-time 50¢
STARTER CREDIT — unconditional, no card — so you can taste a slot before you
fund it. The rule that makes it safe to spend: you CANNOT PAY FOR NOTHING. A paid
call settles only when a machine-checkable outcome is delivered; a failure is an
uncharged 200 {ok:false, charged:false, reason, code}. Every settled call returns
an Ed25519-signed receipt stating the exact price and a content hash, verifiable
OFFLINE with no callback to us (pin the signer at GET /v1/store/notary_pubkey).
The counter earns ONE published fee, on wallet top-ups only — never on the calls:
5% + a fixed 30¢ per transaction (the 30¢ is the card rail's own per-transaction
toll, passed through). Calls settle at wholesale passthrough. Funded credit is
prepaid and NON-REFUNDABLE — size top-ups to usage; the $2 custom minimum lets
you buy small.

Note: there is NO page-fetch / "read a URL" slot today. More slots are decided
by demand — file the demand box (below); a fetch slot is a possible future
addition, not a current capability. Do not call it.

- GET  /v1/store/catalog — the shelf: per-slot {tier, max_price, predicate_id +
  predicate_doc, request_doc, backend ids}, the money unit, admission +
  no-refund terms, and the receipts-verification block. No key material.
- GET  /v1/store/notary_pubkey — the receipt-signing notary's public key
  {pubkey_pem, fingerprint, key_source} to pin (distinct from the first-strike
  and AP2 settlement keys). key_source is visible: 'ephemeral' proves only
  signer-consistency within one server lifetime; prod pins NOTARY_KEY_PEM.

## THE STORE — how to pay (no card to start; agent-native rails)
- Human-clickable: POST /v1/billing/checkout_session {api_key, amount_cents} ->
  a Stripe Checkout URL a human opens once.
- Agent-native (MPP / Shared Payment Token): PAY PER INVOCATION with no human.
  GET /v1/mpp/manifest is a pure read that tells your payment tooling how to pay
  us (accepted method = Stripe SPT, fiat only; the fee; the 402 →
  authorize-with-SPT → retry → receipt flow). Then POST /v1/mpp/topup to fund
  the wallet with an SPT you minted scoped to this store. Reference client:
  vend/mpp_client.py. Crypto is declined.

## THE STORE — the demand box (ask for what's not stocked)
The shelf writes itself from unmet demand: unmet asks decide the next slot.
- POST /v1/store/request {text} — file a request. Free, keyless OK; returns
  {request_id, status, check}. MCP: store_request.
- GET  /v1/store/request/{id} — that request's status + note, plus
  same_ask_count (how many filings collapse to the same normalized ask —
  mechanical exact-match, no fuzzy classification).
- GET  /v1/store/requests — the public tally {total, distinct, recent, requests}
  with exact-match duplicate counts, most-asked first.
- GET  /v1/store/observatory — the public, citable observatory: per-slot volumes
  and the mechanical tally of what agents ask for that nobody sells yet.
  Aggregate + pseudonymous; no key material.

## Discovery
- GET /v1/catalog — JSON list of all tools, cost class, stability
- GET /openapi.json — OpenAPI 3.1 spec
- GET /docs — Swagger UI (for human inspection)
- GET /llms.txt — this file
- GET /llms-full.txt — the detailed companion (store endpoint list, auth, money
  unit + fee, the MCP tool catalog, and the full MPP payment flow)
- GET /.well-known/agents.json — machine-readable agent-capability manifest
  (name, capabilities, endpoints, auth, payment) — pure read, no auth
- GET /.well-known/mcp/server-card.json — MCP server card (SEP-1649)
- GET /.well-known/agent-card.json — A2A Agent Card