OpenKarta
SPEC · v0.1 · MIT

Eight verbs. Five item types. One contract.

The OpenKarta protocol defines exactly the surface area an autonomous agent needs to transact — and nothing more. Every type is Zod-checked. Every quote is signed. Every state machine is closed.

View source ↗ npm i @openkarta/spec ↗

Verb × Item type matrix

Verb productstayflightbusservice
discover circle circle circle circle circle
search circle circle circle circle circle
get circle circle circle circle circle
quote circle circle circle circle circle
checkout circle circle circle circle circle
status circle circle circle circle circle
cancel circle circle circle circle circle
return circle — — — —

return applies only to physical product orders. All other verbs are required for every supported item type.

Design principles

01. Closed enums

Every status, error, fare class, payment rail is a closed enum. Extensibility happens via new RFCs, not free-form strings.

02. Integer minor units

All money is an integer in the smallest currency unit. ₹1 is 100 paise. Floats are forbidden in the wire format.

03. Signed quote tokens

quote() returns an HMAC-signed token bound to the exact item, agent, and TTL. checkout() verifies the signature.

04. No merchant-of-record

OpenKarta routes data, not money. Settlement and tax compliance are the merchant's responsibility — by design.

05. Region-aware

Every agent declares ISO-3166 regions. The registry filters by region; payment rails per region are explicit.

06. User-token delegation

Every checkout carries a short-lived user delegation token with explicit price-cap, time-cap, and rail-cap claims.

Core syntax

Verbs

discover
Returns the agent's capability manifest — supported verbs, item types, regions, languages, payment rails.
search
Item search with item-type-specific filters. Returns priced, in-stock options with provenance.
get
Fetches a single item or fixture by id. Idempotent. Useful for hydration of remembered references.
quote
Server-signed, time-bounded price lock. Inventory committed to the agent for the quote's TTL.
checkout
Exchanges a signed quote for an order. Payment intent issued out-of-band via the chosen rail.
status
Polls order state. Closed enum lifecycle per item type — no free-form strings.
cancel
Cancels a pending order. Returns canonical cancellation receipt with refund-state hint.
return
Initiates a return / refund flow for product orders post-delivery.

Item types

product
Physical goods. Categories, service areas, delivery modes, return window.
stay
Hotels, homestays, apartments, villas, hostels. check_in / check_out, occupancy.
flight
IATA-coded routes, fare classes, passenger manifest objects required at checkout.
bus
Intercity bus operators, regions, seat classes (sleeper, ac-sleeper, volvo, …).
service
Salon, cleaning, repair. At-customer / at-provider / online / venue location modes.

Wire format

A signed quote
{
  "quoteId":     "qt_01J...",
  "itemId":      "tokai-blend-250g",
  "totalMinor":  78000,
  "currency":    "INR",
  "ttlMs":       180000,
  "issuedAt":    1731686400000,
  "signature":   "hmac-sha256:a1b2c3..."
}
A discover() response
{
  "agentId":         "halcyon-shop",
  "protocolVersion": "0.1",
  "tier":            "http",
  "actions":         ["discover","search",...],
  "supportedItemTypes": ["product"],
  "paymentRails":    ["razorpay_routes","cod"],
  "regions":         [{"country":"IN"}]
}

Administrative posture

Versioning & deprecation

The wire format is semver. Major bumps require an 18-month deprecation window. v0.x is pre-1.0 — breaking changes are allowed but always shipped via a parallel package version.

Changelog

RFCs

Modifications are proposed as GitHub issues tagged rfc. Acceptance requires a reference implementation, conformance update, and review from the foundation working group.

View RFCs ↗

Compliance bounds

The protocol defines data structures, not legal agreements. KYC, AML, taxation, GST/VAT routing, and GDPR/CCPA data minimization are the merchant's responsibility within their jurisdiction.

Governance