Calmar
Developer docs

Build on Calmar

One endpoint for agents (Claude, Cursor and anything that connects to tools over MCP) and REST for everything else. Both use one key, from Developers. Pass it as ?key= on the agent URL or Authorization: Bearer on REST.

For agents: one config line

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

With a key, orders your agent places earn you half of what the winning store paid. Tools: procure · checkout · travel_search · travel_book · retail_search · retail_buy · retail_status · order_status · my_orders · request_refund · earnings. Travel books a Duffel test flight or stay on Duffel's balance. Retail searches a Zinc catalog and places the order on Zinc's test wallet; poll retail_status because Zinc finishes the order later. Do not send card numbers. The supplier order id comes back on the booking, and the earning sits pending like any other order.

REST: for agent developers

shell
# 1 · run the auction for what the buyer wants
curl -X POST https://trycalmar.com/api/v1/procure \
  -H "Authorization: Bearer YOUR_CLMR_KEY" -H "Content-Type: application/json" \
  -d '{"query":"65W USB-C charger","maxPriceUsd":35,"region":"US","maxDeliveryDays":2}'
# -> winner, ranked alternatives, clearing price, checkoutToken (valid 15 minutes)

# 2 · place the order once the buyer agrees
curl -X POST https://trycalmar.com/api/v1/checkout \
  -H "Authorization: Bearer YOUR_CLMR_KEY" -H "Content-Type: application/json" \
  -d '{"checkoutToken":"chk_…","buyerRef":"buyer_123",
       "buyerName":"Ada Lovelace",
       "shippingAddress":"1 Main St, Austin TX 78701, US"}'

# 3 · track it, or ask for a refund
curl https://trycalmar.com/api/orders/ord_…
curl -X POST https://trycalmar.com/api/orders/ord_… -H "Content-Type: application/json" \
  -d '{"actor":"buyer","action":"request_refund","text":"arrived damaged"}'

# 4 · what you have earned, and getting paid
curl https://trycalmar.com/api/v1/earnings -H "Authorization: Bearer YOUR_CLMR_KEY"
curl -X POST https://trycalmar.com/api/v1/payouts -H "Authorization: Bearer YOUR_CLMR_KEY" \
  -H "Content-Type: application/json" -d '{"action":"connect"}'    # link a bank account
curl -X POST https://trycalmar.com/api/v1/payouts -H "Authorization: Bearer YOUR_CLMR_KEY" \
  -H "Content-Type: application/json" -d '{"action":"withdraw"}'

REST: for stores

shell
# connect a catalog (shopify | woocommerce | url | csv | json)
# the first call returns your store's API key
curl -X POST https://trycalmar.com/api/connect -H "Content-Type: application/json" \
  -d '{"sellerRef":"store_123","source":"url",
       "url":"https://anystore.com/products/thing"}'

# set what you will pay to win an order, and an optional buyer discount
curl -X POST https://trycalmar.com/api/v1/bids -H "Authorization: Bearer YOUR_STORE_KEY" \
  -H "Content-Type: application/json" -d '{"bidPct":0.10,"rebatePct":0.03}'

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

All endpoints

POST/api/v1/procureRun the auction. Returns the winner, alternatives and a checkoutToken.
POST/api/v1/checkoutPlace the order the auction chose. If the buyer has no card yet you get action: save_card and a url to send them. Add practice: true for a test order that charges nothing.
GET/api/v1/earningsPending, available, paid and reversed earnings for your key.
GET/api/v1/payoutsBalance and whether a bank account is connected.
POST/api/v1/payoutsaction: connect (link a bank account) or withdraw.
GET/api/v1/linksYour buyer links and whether each has a card saved.
POST/api/v1/linksCreate a buyer link. Send label, get back url and buyerRef.
GET/api/v1/bidsA store's current bid and rebate.
POST/api/v1/bidsSet bidPerOrderUsd, bidPct, rebatePct.
POST/api/v1/travel/searchSearch Duffel test flights (origin, destination, date, passengers) or stays (location, dates, guests). Off when no test token is set.
POST/api/v1/travel/bookBook one Duffel offer on the Duffel test balance. Do not send card data. Returns the Duffel order id and a pending ledger entry.
POST/api/v1/retail/searchSearch a Zinc retailer (amazon, walmart, target) or load one product by id. Off when no test key is set.
POST/api/v1/retail/buyPlace one Zinc order on the Zinc test wallet. Do not send card data. Returns the Zinc order id and a pending ledger entry.
POST/api/v1/retail/statusPoll a Zinc order. Placement finishes after the buy call.
POST/api/connectImport a catalog: shopify, woocommerce, url, csv, json.
GET/api/orders?buyerRef=…A buyer's orders.
GET/api/orders/{orderId}One order and its message thread.
POST/api/orders/{orderId}mark_shipped, request_refund, approve_refund, message.
GET/api/sales?sellerRef=…Orders a store won, with shipping addresses.
POST/api/keysSelf-serve API key.

Order state machine

status (money): settled → refund_requested → refunded.
shipStatus (package): none → shipped → in_transit → delivered.
earnings: pending → available → paid after a 30 day return window, or reversed on a refund.
Every order carries agentId — pass agentName (MCP) or X-Agent-Id (REST) so sellers see which agent ordered.