Calmar
Developer docs

Build on Calmar

Two surfaces, one engine. vend for agents (Claude, Cursor, OpenClaw, anything that connects to tools) and REST for everything else. Auth is one key (clmr_…) minted at /keys. Pass it as ?key= on the vend URL or Authorization: Bearer on REST. Interop note for builders: vend speaks MCP on the wire, so every MCP client already works with zero changes.

vend — one config line

agent config
{
  "mcpServers": {
    "calmar": {
      "type": "http",
      "url": "https://trycalmar.com/api/mcp?key=YOUR_CLMR_KEY"
    }
  }
}

With a key, tools know who you are (no refs needed). 19 tools: get_started · find_offers · get_offer · buy · order_my_usual · create_standing_order · my_orders · order_status · request_refund · send_order_message · my_sales · mark_shipped · approve_refund · list_from_photo · create_listing · add_photo_to_listing · connect_catalog · my_listings · update_listing

REST — buying, end to end

shell
# 1 · find offers
curl "https://trycalmar.com/api/offers?query=sparkling+water&maxPrice=30"

# 2 · quote (no money moves)
curl -X POST https://trycalmar.com/api/buy -H "Content-Type: application/json" \
  -d '{"offerId":"off_…","quantity":1}'

# 3 · execute with delivery details + agent identity
curl -X POST https://trycalmar.com/api/buy -H "Content-Type: application/json" \
  -H "X-Agent-Id: my-procurement-bot" \
  -d '{"offerId":"off_…","buyerRef":"buyer_123","confirm":true,
       "buyerName":"Ada Lovelace",
       "shippingAddress":"1 Main St, Austin TX 78701, US"}'

# 4 · track / post-purchase
curl https://trycalmar.com/api/orders/ord_…            # status + message thread
curl -X POST https://trycalmar.com/api/orders/ord_… \
  -H "Content-Type: application/json" \
  -d '{"actor":"buyer","action":"request_refund","text":"arrived damaged"}'

REST — selling, end to end

shell
# list one item (returns your API key on first call)
curl -X POST https://trycalmar.com/api/listings -H "Content-Type: application/json" \
  -d '{"sellerRef":"seller_123","title":"Espresso beans 1kg","priceUsd":21}'

# list from a photo — AI writes title/description/price
curl -X POST https://trycalmar.com/api/list-from-photo -H "Content-Type: application/json" \
  -d '{"sellerRef":"seller_123","image":"https://…/photo.jpg"}'

# connect a whole catalog (shopify | woocommerce | url | csv | json)
curl -X POST https://trycalmar.com/api/connect -H "Content-Type: application/json" \
  -d '{"sellerRef":"seller_123","source":"url",
       "url":"https://anystore.com/products/thing"}'

# your sales; mark shipped; approve refunds
curl "https://trycalmar.com/api/sales?sellerRef=seller_123"
curl -X POST https://trycalmar.com/api/orders/ord_… -H "Content-Type: application/json" \
  -d '{"actor":"seller","action":"mark_shipped"}'

All endpoints

GET/api/marketPublic catalog. Filters: q, vertical, maxPrice, fulfillment.
GET/api/offers?query=…Ranked, valid offers for a buyer intent (validity first, then value).
POST/api/order-my-usualNatural-language intent → best offer via AI reasoning → quote or buy.
POST/api/buyQuote (confirm=false) or execute (confirm=true + shippingAddress + buyerName).
GET/api/orders?buyerRef=…Buyer order history with strict statuses.
GET/api/orders/{orderId}One order + buyer-seller message thread.
POST/api/orders/{orderId}Lifecycle: mark_shipped, request_refund, approve_refund, cancel, message.
GET/api/sales?sellerRef=…Seller view: orders on your listings, with shipping addresses.
POST/api/listingsCreate a listing. GET with ?sellerRef= lists yours.
POST/api/list-from-photoPhoto → AI-drafted, priced, published listing.
POST/api/connectImport a catalog: shopify, woocommerce, url (AI extract), csv, json.
POST/api/keysSelf-serve API key for a sellerRef (idempotent).

Order state machine

status (money): pending_confirmation → settled → refund_requested → refunded, or cancelled (before settle).
shipStatus (package): label_created → awaiting_dropoff → shipped → in_transit → delivered (C2C); brands start at none → shipped.
Every order carries agentId — pass agentName (MCP) or X-Agent-Id (REST) so sellers see which agent ordered.