Every OANP session has exactly three roles — Buyer, Arbiter, and Merchant. Each role has a distinct purpose and a distinct trust boundary. No role can be merged with another within a session.

The roles

Buyer Agent. Represents the party wishing to acquire an item or service. Holds the user's constraints and preferences privately. Sends session.open, offer.propose, and ultimately receives the signed agreement.

Merchant Agent. Represents the party offering the item or service. Holds internal floor prices, policy constraints, and inventory status privately. Sends session.ack, offer.counter, and offer.accept.

Arbiter. Structurally neutral. Does not represent either party. Observes every message, verifies it against the session's committed rules, and emits a round.verdict per round. Signs the final session.agree artifact when all invariants are satisfied.

Who can be an arbiter?

OANP defines the arbiter as a role, not a vendor. Any party can fulfill the role provided they commit to the seven invariants and emit verdicts that match the session log. Expected operators:

• Platforms that want to certify their own marketplace is fair.
• Independent non-profits (e.g. consumer protection orgs).
• Merchant consortiums running shared arbiters to reduce overhead.
• Specialized arbiter startups whose value prop is neutrality itself.

The pattern is the same as TLS certificate authorities or DNS resolvers: multiple implementations, one protocol, one set of rules.

OANP is built on a simple privacy guarantee: neither the buyer, nor the merchant, nor the arbiter ever sees the other side's private constraints. What crosses boundaries are hash commitments, public offers, and the arbiter's verdicts.

Three vaults, one session

At session open, each agent computes a cryptographic commitment to its private constraints and sends that commitment to the arbiter. The constraint values themselves never leave the agent's own process. The arbiter stores only the hashes.

session.open {
  role: "buyer",
  session_id: "01HXYZ...",
  constraints_commit: "0x8f3a...",  ← hash only
}

If either side tries to change its constraints mid-session — say a merchant raising its floor after seeing the buyer's first offer — the next message will not verify against the original commitment. Invariant I3 (constraint immutability) catches it.

What the arbiter sees

• Both parties' hash commitments at session open.
• Every offer.propose, offer.counter, and offer.accept passing between them.
• The public parts of each round — quoted prices, accepted terms, concession direction.
• The arbiter's own emitted verdicts, signed into the session log.

What the arbiter does not see

• The buyer's true ceiling or budget.
• The merchant's floor price or pricing strategy.
• Either side's internal reasoning, utility weights, or alternative options.
• Either side's commitment plaintext (only the hash).

Seven MUST invariants (I1–I7) that every conformant OANP session satisfies. Each invariant is stated in a form that is mechanically checkable from the session's message log, which means compliance is verifiable, not assumed.

Default profile

v0.1 ships with a default fairness profile, default/v0.1, that specifies how an arbiter decides whether a round's moves are "within bounds". Profiles are pluggable — a session can negotiate a different profile at open — but any profile MUST still enforce I1–I7.

OANP messages are plain JSON with a type discriminator. Seven message types cover the full session lifecycle. JWS detached signatures are required only on the final session.agree artifact.

Envelope

{
  "oanp_version": "0.1",
  "message_id": "01HXYZ...",
  "session_id": "01HXYW...",
  "timestamp": "2026-04-22T00:00:00Z",
  "sender": { "role": "buyer" | "merchant" | "arbiter", "agent_id": "..." },
  "type": "",
  "payload": { ... }
}

Message types

1. session.open — buyer initiates; includes constraint commitment
2. session.ack — merchant acknowledges; includes their commitment
3. offer.propose — any side proposes an offer value
4. offer.counter — counter-offer from the opposite side
5. offer.accept — either side accepts the standing offer
6. round.verdict — arbiter emits fairness verdict per round
7. session.agree — JWS-signed final artifact

OANP is designed to coexist with the existing agent commerce stack, not replace it. It fills the middle phase — negotiation — between discovery (MCP / UCP) and payment (ACP / TAP).

The three phases of agent commerce

1. Discovery — a buyer agent finds merchants it might want to transact with. Handled by MCP, UCP, A2A.
2. Negotiation — the parties agree on terms. Handled by OANP.
3. Payment — the deal is settled. Handled by ACP, TAP, Agent Pay.

How OANP carries inside other protocols

Any transport that can carry a JSON object can carry an OANP session. Reference transports in v0.1:

• MCP tool call: OANP messages travel as the body of an MCP tool invocation. Recipients parse the envelope's type field.
• HTTPS POST: synchronous request/response between agents.
• Server-sent events: arbiter streams verdicts to both parties.

Handoff to ACP

A signed session.agree artifact is structured so its digest slots cleanly into checkout_session.create metadata. That means an ACP-compatible payment processor can verify the negotiated terms before charging.

A runnable OANP v0.1 session in under two minutes. Clone the reference repo, run one command, watch a complete SFO → JFK negotiation print every envelope plus the signed agreement.

1. Clone and run

git clone https://github.com/oanp-protocol/reference
cd reference
uv sync
uv run oanp-ref demo

Requires uv + Python 3.11+. Zero runtime dependencies; dev tools are pytest + coverage only. You'll see the full message sequence below, round-by-round verdicts from the arbiter, and the final signed artifact.

Prefer library use? from oanp_ref import BuyerAgent, MerchantAgent, Arbiter.

2. What each message looks like

Every OANP message is a plain JSON envelope. Here's the opening message the Buyer Agent sends:

{
  "oanp_version": "0.1",
  "message_id": "01D15651843C02F1860C180602",
  "session_id": "0153F5DB7DED18746A7BAD5CC5",
  "timestamp": "2026-04-28T14:00:00Z",
  "sender": {
    "role": "buyer",
    "agent_id": "buyer-001"
  },
  "type": "session.open",
  "payload": {
    "item": { "route": "SFO-JFK", "date": "2026-04-28" },
    "max_rounds": 5,
    "constraints_commit": "0xfd6b8b899c3e4309"
  }
}

Notice what isn't in that payload: the buyer's true ceiling, budget, urgency, or seat preferences. All of that stays private to the buyer's process. The arbiter receives only the constraints_commit — a SHA-256 hash of the canonicalized constraints. If the buyer tries to change them mid-session, the commitment won't match (invariant I3).

3. A complete round

Round 1 of the negotiation, in full:

// Buyer proposes $320
{ "type": "offer.propose",
  "sender": { "role": "buyer", "agent_id": "buyer-001" },
  "payload": { "round": 1, "price": 320 } }

// Merchant counters $370
{ "type": "offer.counter",
  "sender": { "role": "merchant", "agent_id": "united-merchant-001" },
  "payload": { "round": 1, "price": 370 } }

// Arbiter emits verdict
{ "type": "round.verdict",
  "sender": { "role": "arbiter", "agent_id": "arbiter-001" },
  "payload": {
    "round": 1,
    "status": "fair",
    "rationale": "opening moves within committed rules"
  } }

4. Signed agreement

When both sides accept, the arbiter produces a session.agree with a detached signature over the full session digest:

{ "type": "session.agree",
  "sender": { "role": "arbiter", "agent_id": "arbiter-001" },
  "payload": {
    "final_price": 340,
    "session_digest": "af60fd3b38c0a574...",
    "signature": "b767c59b848ea50b...",
    "signature_alg": "HS256",
    "invariants_satisfied": ["I1","I2","I3","I4","I5","I6","I7"]
  } }

That digest + signature is what an ACP processor would attach as metadata on checkout_session.create — the agreement becomes the authorization for payment.

OANP is structurally simple: three roles, seven message types, one privacy boundary per role. This page shows where OANP sits in the agent commerce stack and how the three roles compose.

Where OANP sits

OANP fills the negotiation phase between discovery and payment in agent commerce:

The three-role structure

Inside a single OANP session, three roles exchange messages with distinct trust boundaries:

Message flow

A session produces exactly seven message types, exchanged in a fixed order:

1. session.open — Buyer opens, includes constraint commitment
2. session.ack — Merchant acknowledges, includes their commitment
3. offer.propose / offer.counter — round-by-round exchange
4. round.verdict — Arbiter emits after each round
5. offer.accept — Either side accepts the standing offer
6. session.agree — Arbiter signs the final artifact

See Message format for the full envelope spec and Session state machine for the transition diagram.

See the three-role model for the full breakdown of Buyer, Arbiter, and Merchant responsibilities.

An OANP session moves through four states. The arbiter is the authority for all transitions; both parties observe the arbiter's verdicts and react accordingly.

State definitions

• OPENING — Buyer has sent session.open. Waiting for merchant's session.ack. Both constraint commitments are locked at this point (I3).
• NEGOTIATING — Rounds of offer.propose / offer.counter. Each round must complete before entering EVALUATING.
• EVALUATING — Arbiter has observed a round's moves and is emitting a round.verdict. If the verdict is fair and no acceptance, session returns to NEGOTIATING. If an acceptance arrived, transitions to AGREED.
• AGREED — Terminal. Arbiter signs session.agree over the full session digest (I6). The signed artifact is the handoff to ACP checkout.
• CLOSED — Terminal. Session ended without agreement. Possible reasons: max_rounds exceeded (I1), I4 violation (either side reneging), buyer withdraws, timeout, or arbiter-detected invariant failure.

Transition rules

• Only the arbiter transitions states. Buyer and merchant observe verdicts and react; they do not unilaterally advance the state.
• Every NEGOTIATING → EVALUATING transition emits exactly one round.verdict (I5).
• Every terminal state writes a final message: session.agree for AGREED, session.close with a reason code for CLOSED.

OANP uses SemVer. v0.1 is the initial draft; v0.2 will add multi-merchant sessions and richer fairness profiles.

A Buyer Agent represents the user. It opens sessions, proposes offers, decides whether to concede or accept, and receives the signed agreement. Its private vault (true ceiling, urgency, preferences) never leaves its process.

Responsibilities

• Hold the user's private constraints — budget, true ceiling, urgency, preferences.
• Open the session with a hash commitment over those constraints (I3).
• Emit offer.propose values that monotonically concede toward agreement (I4).
• Decide, each round, whether to continue, accept, or withdraw — using only the merchant's public moves and its own private vault.
• Never expose vault values outside the agent process, and never violate its own commitment.

Reference code

Excerpt from src/oanp_ref/buyer.py:

class BuyerAgent:
    def __init__(self, agent_id, constraints):
        # Private vault — never leaves this object.
        self._constraints = dict(constraints)
        self.agent_id = agent_id
        self.session_id = None
        self._offers = []

    def open(self, session_id, item, max_rounds=5):
        self.session_id = session_id
        to_commit = {
            "constraints": self._constraints,
            "item": item,
            "max_rounds": max_rounds,
        }
        self._committed = commit_constraints(to_commit)
        return make_envelope(
            session_id, "buyer", self.agent_id, "session.open",
            {"item": item, "max_rounds": max_rounds,
             "constraints_commit": self._committed},
        )

    def propose(self, price):
        if price > self._constraints["true_ceiling"]:
            raise ValueError("would exceed private ceiling")
        if self._offers and price < self._offers[-1]:
            raise ValueError("I4 violation: must concede, not renege")
        self._offers.append(price)
        return make_envelope(
            self.session_id, "buyer", self.agent_id, "offer.propose",
            {"round": len(self._offers), "price": price},
        )

A Merchant Agent represents the seller. It responds to session.open, counters buyer offers, and accepts when the buyer reaches a price above its private floor. Floor price and pricing strategy never leave its process.

Responsibilities

• Hold the merchant's private constraints — floor price, ideal price, inventory pressure, strategy parameters.
• Acknowledge the session with its own constraint commitment (I3).
• Decide, for each offer.propose, whether to counter or accept — using only the buyer's public offer and its own private vault.
• Counter values must monotonically decrease toward agreement (I4). Once accepted, no reneging.
• Never expose vault values (especially the floor price) in any wire message.

Reference code

Excerpt from src/oanp_ref/merchant.py:

class MerchantAgent:
    def __init__(self, agent_id, constraints):
        # Private vault — never leaves this object.
        self._constraints = dict(constraints)
        self.agent_id = agent_id
        self.session_id = None
        self._counters = []

    def handle_propose(self, buyer_price):
        floor = self._constraints["floor_price"]
        ideal = self._constraints["ideal_price"]

        if buyer_price >= ideal:
            return self._accept(buyer_price)            # good enough
        if buyer_price < floor:
            counter = self._counters[-1] - 15 if self._counters else ideal + 10
            return self._counter(max(counter, floor))    # stay above floor

        # Between floor and ideal — concede a little, stay above floor.
        next_counter = max(self._counters[-1] - 15, buyer_price + 5, floor)
        if next_counter >= self._counters[-1]:
            return self._accept(buyer_price)             # would renege; accept instead
        return self._counter(next_counter)

    def _counter(self, price):
        if self._counters and price > self._counters[-1]:
            raise ValueError("I4 violation: counter went up")
        self._counters.append(price)
        return make_envelope(self.session_id, "merchant", self.agent_id,
                             "offer.counter",
                             {"round": len(self._counters), "price": price})

An Arbiter is the neutral third role. It observes every message, enforces the seven fairness invariants in real time, emits one round.verdict per round, and JWS-signs the final session.agree. It holds commitments, not values.

Responsibilities

• Observe every protocol message; maintain the session log for I7 (auditable history).
• Enforce I4 — monotonic concession on both sides. Raise if a buyer reneges (lowers) or a merchant reneges (raises).
• Enforce I1 — bounded rounds. Close the session if round count exceeds max_rounds.
• Emit one verdict per round (I5) with a status (fair / fair_but_stuck / violated) and a short rationale.
• Sign the final artifact over a digest of the full log (I6), using JWS detached signatures.

Reference code

Excerpt from src/oanp_ref/arbiter.py:

class Arbiter:
    def __init__(self, agent_id, max_rounds=5):
        self.agent_id = agent_id
        self.max_rounds = max_rounds
        self.log = []                    # I7 — auditable history
        self.buyer_offers = []
        self.merchant_counters = []
        self.verdicts = []

    def observe(self, env):
        self.log.append(env.to_json())
        if env.type == "offer.propose":
            # I4 — buyer's offers must move up toward agreement.
            if self.buyer_offers and env.payload["price"] < self.buyer_offers[-1]:
                raise ArbiterError("I4: buyer reneged")
            self.buyer_offers.append(env.payload["price"])
        elif env.type == "offer.counter":
            if self.merchant_counters and env.payload["price"] > self.merchant_counters[-1]:
                raise ArbiterError("I4: merchant reneged")
            self.merchant_counters.append(env.payload["price"])

    def emit_round_verdict(self):
        round_n = min(len(self.buyer_offers), len(self.merchant_counters))
        # I1 — bounded rounds
        if round_n > self.max_rounds:
            raise ArbiterError("I1: exceeded max_rounds")
        spread = self.merchant_counters[round_n-1] - self.buyer_offers[round_n-1]
        if round_n > 1:
            prior = self.merchant_counters[round_n-2] - self.buyer_offers[round_n-2]
            status = "fair" if spread < prior else "fair_but_stuck"
        else:
            status = "fair"
        return make_envelope(self.session_id, "arbiter", self.agent_id,
                             "round.verdict", {"round": round_n, "status": status, ...})

    def sign_agreement(self, price, key):
        digest = session_digest(self.log)
        signature = sign(digest, key)    # JWS detached in production
        return make_envelope(self.session_id, "arbiter", self.agent_id,
                             "session.agree",
                             {"final_price": price, "session_digest": digest,
                              "signature": signature, "signature_alg": "HS256",
                              "invariants_satisfied": list(INVARIANTS.keys())})

Operating an arbiter as a service

The reference code runs in-process. In production, arbiters typically run as a hosted service with:

• A public endpoint (HTTPS POST, MCP tool, or SSE) that accepts OANP envelopes.
• A persisted session log — minimum retention covers the dispute window for whatever domain is being arbitrated.
• A signing key rotated on a fixed schedule. Public verification keys published at a well-known URL.
• A monitoring surface that tracks invariant-violation rates — high rates indicate misconfigured counterparties or attempted abuse.

Full specification of the three-role state machine, the happy path, and fairness-violation recovery.

Checklist for verifying an implementation complies with v0.1.