Quickstart

Vibe commerce is one transaction spoken between two agents over one envelope shape. This page shows what building on that surface will look like, and the three things you can do with it right now.

Three ways in

Two of these are available today; the third is the beta you can request.

• Read the spec. Start with the protocol itself — the Vibe Commerce Protocol for the model and namespaces, then the universal envelope for the wire shape every message takes.
• Experiment. The protocol ships with a deterministic scenario corpus. A run is byte-exact replayable from (audit_log, world_seed), so you can step through search, negotiation, settlement, and dispute flows without a live endpoint and get the same result every time.
• Build. Request private-beta access to send real envelopes against the hosted runtime. The snippets below are the shape your integration will speak.

Your first envelope

Here is how a discovery request will look: a buyer's buyer:discovery role sends a commerce.search envelope to platform:aggregator. The transport is a single POST /vcp with the envelope as the body. This is the intended, beta-gated shape — the token below is a placeholder, not a credential that resolves today.

# DESIGN PREVIEW — beta-gated, not a live public endpoint.
# The intended shape of sending a commerce.search envelope.
curl https://api.springbrand.example/vcp \
  -H "Authorization: Bearer $SPRINGBRAND_BETA_TOKEN" \
  -H "Content-Type: application/json" \
  -d @envelope.json

The body is one VCP envelope. Every message — search, offer, settlement — uses this same outer shape; only action.kind and action.payload change. Money is always integer minor units, so a $500 budget is 50000.

{
  "protocol": "vcp",
  "version": "1.0",
  "msg_id": "msg_001",
  "ts": "2026-05-31T12:00:00Z",
  "from": "buyer:discovery",
  "to": "platform:aggregator",
  "session_id": "sess_abc",
  "in_reply_to": null,
  "idempotency_key": "idem_001",
  "action": {
    "kind": "commerce.search",
    "payload": {
      "query": "premium calm home office setup",
      "hard_constraints": {
        "budget": 50000,
        "delivery_days": 5,
        "must_have": ["minimalist", "warm_lighting"]
      },
      "soft_preferences": {
        "style": ["quiet_luxury", "japanese_minimalist"]
      }
    }
  }
}

What you get back

The aggregator answers with a platform.rank_offersenvelope carrying ranked candidates: grounded offers with prices, fulfillment terms, the claims the platform verified, and each merchant's reputation. The response below is representative — an illustration of the shape, with example values, not output from a live call.

{
  "protocol": "vcp",
  "version": "1.0",
  "msg_id": "msg_002",
  "in_reply_to": "msg_001",
  "from": "platform:aggregator",
  "to": "buyer:discovery",
  "action": {
    "kind": "platform.rank_offers",
    "payload": {
      "candidates": [
        {
          "offer_id": "off_511",
          "merchant_id": "merchant:atelier",
          "sku_id": "sku_desk_oak",
          "unit_price": 41900,
          "fulfillment": { "method": "courier", "eta_days": 3 },
          "claims": ["solid_oak", "warm_lighting_bundle"],
          "reputation": { "rolling_avg": 4.62, "n_settled": 118 }
        }
      ],
      "verification_policy": "vp.2026.05"
    }
  }
}

From here the intended flow continues in the same envelope shape: commerce.propose_offer and commerce.counter_offer to negotiate, then commerce.create_cart and a platform-issued MatchCertificate before settlement.

Authority & limits

Every integration sets one block that defines the safety envelope your agent operates inside: the buyer authority block on the PurchaseMandate. It is the first thing to configure, because it bounds what the agent may do without coming back to the human.

authority:
  can_buy_without_confirmation: false   # agent must ask before it commits
  max_spend_without_confirmation: 20000 # minor units; ceiling on silent spend
  can_negotiate: true
  can_accept_substitutes: false
  must_not_share_with_merchant:         # tagged PRIVATE_UTILITY
    - reservation_price
    - max_budget

• can_buy_without_confirmation — whether the agent may settle at all without an explicit human approval.
• max_spend_without_confirmation — the ceiling, in minor units, on any spend the agent makes silently. Above it, settlement requires a delegate.approve_purchase.
• must_not_share_with_merchant — values tagged PRIVATE_UTILITY that the runtime drops from any outbound payload, so your reservation price never goes on the wire.