Build on Calmar. One key, MCP or REST.
MCP for agents, REST for everything else. One key for both.
- Base URL
- https://calmar.sh
- Auth
- Authorization: Bearer KEY
- MCP
- /api/mcp?key=KEY
- Sandbox
- keys starting sk_test_
Works with
- Claude
- Cursor
- ChatGPT
- Gemini
- Perplexity
- LangChain
- Vercel AI SDK
- GitHub Copilot
- Windsurf
#Quickstart
- 1Get a key
Make a live key and a test key on your dashboard.
Open keys - 2Connect your agent
One line for Claude Code, Cursor or any MCP client.
Connect - 3Place a test order
Search, then a practice checkout. No money moves.
Try it
#Connect an agent
Add ?key= to the agent URL. Orders placed with your key earn you half the winning store's fee.
claude mcp add --transport http calmar https://calmar.sh/api/mcp#Search before answering
Calmar tells connected agents to search first, so a buy request goes to calmar_search, not the model's memory. If your agent has its own system prompt, add this line. Every result has a next field that says how to finish the order.
When the user wants to buy, order or book something, call the calmar_search tool with their request before replying. Do not recommend products, stores or prices from your own knowledge. Then follow the `next` field in the result.
#Buy for a buyer
Four calls from a request to money in your bank. REST, with your key.
- 1Run the auction
Send what the buyer wants and their limits. You get the winner, ranked alternatives, the clearing price and a checkoutToken valid for 15 minutes.
shellcurl -X POST https://calmar.sh/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}' - 2Place the order once the buyer agrees
Send the token and who the order is for. If the buyer has no card saved yet, the answer is action: save_card with a url to send them.
shellcurl -X POST https://calmar.sh/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"}' - 3Track it, or ask for a refundshell
curl https://calmar.sh/api/orders/ord_… curl -X POST https://calmar.sh/api/orders/ord_… -H "Content-Type: application/json" \ -d '{"actor":"buyer","action":"request_refund","text":"arrived damaged"}' - 4See what you earned, and get paid
Link a bank account once, then withdraw what is available.
shellcurl https://calmar.sh/api/v1/earnings -H "Authorization: Bearer YOUR_CLMR_KEY" curl -X POST https://calmar.sh/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://calmar.sh/api/v1/payouts -H "Authorization: Bearer YOUR_CLMR_KEY" \ -H "Content-Type: application/json" -d '{"action":"withdraw"}'
#Test keys
A test key starts with sk_test_. Create one on your dashboard, then connect your agent. It reaches only sample stores and test suppliers: no card is charged, nothing is paid out, no real store gets an order.
- 1The same auction, over the sample stores only
The answer says "mode":"test" and comes from a sample store, with a checkoutToken.
shellcurl -X POST https://calmar.sh/api/v1/procure \ -H "Authorization: Bearer sk_test_YOUR_TEST_KEY" -H "Content-Type: application/json" \ -d '{"query":"65W USB-C charger","maxPriceUsd":35}' - 2A practice order
No card, no charge, no real store is told. The receipt says "Practice order. No money moved."
shellcurl -X POST https://calmar.sh/api/v1/checkout \ -H "Authorization: Bearer sk_test_YOUR_TEST_KEY" -H "Content-Type: application/json" \ -d '{"checkoutToken":"chk_…","buyerRef":"buyer_123", "buyerName":"Ada Lovelace", "shippingAddress":"1 Main St, Austin TX 78701, US"}' - 3Or connect an agent in test modeshell
claude mcp add --transport http calmar-test "https://calmar.sh/api/mcp?key=sk_test_YOUR_TEST_KEY"
No account? The API console runs search, quote and checkout on a visitor test key: those three calls only, one hour, 30 requests a minute.
#Know your agent
Register each agent you run. It gets its own key, per-order and daily limits, and a spend record. An order over a limit is refused before money moves; pause or revoke an agent any time. The passport is a signed statement of who the agent is, your account's standing and the order it is placing. A store or payment processor can verify it on its own.
- 1Register the agent with your account key
You get the agent's own key, once.
shellcurl -X POST https://calmar.sh/api/v1/agents \ -H "Authorization: Bearer YOUR_CLMR_KEY" -H "Content-Type: application/json" \ -d '{"name":"Trip planner","maxPerOrderUsd":250,"dailyCapUsd":600}' - 2Connect the agent with its own key
Every order it places is checked against its limits.
shellclaude mcp add --transport http calmar "https://calmar.sh/api/mcp?key=THE_AGENT_KEY"
- 3Get a signed passport for the order it is about to placeshell
curl -X POST https://calmar.sh/api/v1/agents/passport \ -H "Authorization: Bearer THE_AGENT_KEY" -H "Content-Type: application/json" \ -d '{"checkoutToken":"chk_…"}' - 4Anyone can check itshell
curl -X POST https://calmar.sh/api/v1/agents/verify -H "Content-Type: application/json" \ -d '{"passport":"eyJ…"}'
#Sell as a store
Connect your catalog once; agents find it from then on.
- 1Connect a catalog
shopify, woocommerce, url, csv or json. The first call returns your store's API key.
shellcurl -X POST https://calmar.sh/api/connect -H "Content-Type: application/json" \ -d '{"sellerRef":"store_123","source":"url", "url":"https://anystore.com/products/thing"}' - 2Set what you pay to win an order
And, if you like, a discount for the buyer.
shellcurl -X POST https://calmar.sh/api/v1/bids -H "Authorization: Bearer YOUR_STORE_KEY" \ -H "Content-Type: application/json" -d '{"bidPct":0.10,"rebatePct":0.03}' - 3Your orders: mark shipped, approve refundsshell
curl "https://calmar.sh/api/sales?sellerRef=store_123" curl -X POST https://calmar.sh/api/orders/ord_… -H "Content-Type: application/json" \ -d '{"actor":"seller","action":"mark_shipped"}'
#MCP tools
What a connected agent can call.
- calmar_search
- Search first: one sentence in, the best offer out, and what to do next.
- procure
- Run the catalog auction for a product.
- checkout
- Place the order the auction chose.
- order_status
- Where one order is.
- my_orders
- Everything this key has placed.
- request_refund
- Ask for a refund on an order.
- earnings
- What you have earned so far.
- travel_search · travel_book
- Flights and stays, on the Duffel test balance.
- retail_search · retail_buy · retail_status
- Amazon, Walmart and Target through Zinc, on the Zinc test wallet.
#Endpoints
Search and buy
- POST
/api/v1/searchOne sentence in. Returns a winner that meets every hard limit, a machine-readable pick and cache timing. next says how to finish: a buyUrl for the buyer, or the call that places the order. mode says live or test. Without a key, send x-calmar-mode: test for the sandbox.
- POST
/api/v1/procureRun the catalog auction. Returns the winner, alternatives and a checkoutToken. Not for flights or hotels.
- POST
/api/v1/checkoutPlace the order the auction chose. No card saved yet: you get action: save_card and a url to send the buyer. practice: true charges nothing and no real store is told; in test mode every order is a practice order.
Orders
- GET
/api/v1/ordersJSON list for the API key. Optional buyerRef; otherwise the caller's own ref.
- GET
/api/orders?buyerRef=…A buyer's orders. Requires that buyer's session or an API key that owns them.
- GET
/api/orders/{orderId}One order and its message thread.
- POST
/api/orders/{orderId}mark_shipped, request_refund, approve_refund, message.
Earnings, payouts and buyer links
- 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.
Agents
- GET
/api/v1/agentsYour registered agents, what each spent today, and your account standing.
- POST
/api/v1/agentsRegister an agent: name, and optionally maxPerOrderUsd, dailyCapUsd, verticals. Returns the agent's own key once.
- PATCH
/api/v1/agentsChange an agent's limits, set status to paused, active or revoked, or send newKey: true to replace its key.
- POST
/api/v1/agents/passportCalled with an agent's key. A signed passport, valid ten minutes; add checkoutToken to bind it to one order.
- POST
/api/v1/agents/verifyCheck a passport. Public. Also tells you if the agent has been paused or revoked since.
- GET
/api/v1/agents/jwksThe public key passports are signed with, to check one yourself.
Stores
- POST
/api/connectImport a catalog: shopify, woocommerce, url, csv, json.
- GET
/api/v1/bidsA store's current bid and rebate.
- POST
/api/v1/bidsSet bidPerOrderUsd, bidPct, rebatePct.
- GET
/api/sales?sellerRef=…Orders a store won, with shipping addresses.
Test suppliers
- POST
/api/v1/travel/searchTest mode only. Search Duffel flights or stays. Ranked on the USD total; stops, duration and cabin break a 2% tie. pending: true means ask again in a moment. expiresAt and timing are on the result. Off when no test token is set.
- POST
/api/v1/travel/bookTest mode only. Book 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/searchTest mode only. Search a Zinc retailer (amazon, walmart, target) or load one product by id. Ranked on landed price (item plus shipping). pending: true means ask again in a moment. Off when no test key is set.
- POST
/api/v1/retail/buyTest mode only. Place 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/statusTest mode only. Poll a Zinc order. Placement finishes after the buy call.
Keys
- POST
/api/keysSelf-serve API key.
#Rate limits
Open endpoints are limited per address. With a key the limit is per key, and the key's address gets ten times the per-address limit, so people behind one hosted agent do not share an allowance. Endpoints that call a model or a web search also have a ceiling across all callers. Over a limit you get 429 with Retry-After; every limited response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset.
| Endpoint | Per address | Per key | All callers |
|---|---|---|---|
| POST /api/v1/understand (the playground agent's model call) | 20 per minute, 300 per day | none | 600 per minute, 20,000 per day |
| POST /api/v1/procure | 60 per minute, 2,000 per day | 60 per minute | none |
| POST /api/v1/checkout | 20 per minute, 300 per day | 20 per minute | none |
| Requests made with the playground console's visitor key, on top of the endpoint's own limit | 30 per minute, 600 per day | 30 per minute | 1,200 per minute |
| POST /api/v1/playground/key | 10 per minute, 100 per day | none | 600 per minute |
| POST /api/v1/search | 20 per minute, 500 per day | 120 per minute | none |
| POST /api/v1/retail/search and /travel/search | 20 per minute, 500 per day | 30 per minute | none |
| POST /api/v1/retail/buy and /travel/book | 10 per minute | 10 per minute | none |
| POST /api/v1/retail/status | 30 per minute, 600 per day | 60 per minute | none |
| Live flight prices behind the flight_search tool. Over it, cached fares are shown | 20 per minute, 200 per day | none | 3,000 per day |
| The MCP endpoint, /api/mcp. Each tool also counts against the limit of its REST twin | 120 per minute | 120 per minute | none |
| POST /api/connect | 30 per minute, 200 per day | 30 per minute | none |
| POST /api/connect with source: url, on top of the limit above | 10 per minute, 100 per day | 30 per minute | 300 per minute, 2,000 per day |
| POST /api/partners/preview | 12 per minute, 200 per day | none | none |
| POST /api/keys | 20 per minute | none | none |
| POST /api/billing | 20 per minute | none | none |
HTTP/1.1 429 Too Many Requests
Retry-After: 3
RateLimit-Limit: 20
RateLimit-Remaining: 0
RateLimit-Reset: 3
RateLimit-Policy: 20;w=60
{
"error": "rate_limited",
"message": "Too many requests from this address (20 per minute). Try again in 3 seconds.",
"scope": "ip",
"policy": "playground.understand",
"limit": 20,
"windowSeconds": 60,
"retryAfterSeconds": 3
}#Order states
statusthe moneysettledrefund_requestedrefunded
shipStatusthe packagenoneshippedin_transitdelivered
earningsyour sharependingavailablepaidreversedon a refund
Earnings become available after a 30 day return window. Every order carries agentId: pass agentName (MCP) or X-Agent-Id (REST) so sellers see which agent ordered.