Developer docs

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

  1. 1Get a key

    Make a live key and a test key on your dashboard.

    Open keys
  2. 2Connect your agent

    One line for Claude Code, Cursor or any MCP client.

    Connect
  3. 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.

Terminal. Add ?key=YOUR_CLMR_KEY on the URL when you want orders to earn.
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.

system prompt
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.

  1. 1
    Run 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.

    shell
    curl -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}'
  2. 2
    Place 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.

    shell
    curl -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"}'
  3. 3
    Track it, or ask for a refund
    shell
    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"}'
  4. 4
    See what you earned, and get paid

    Link a bank account once, then withdraw what is available.

    shell
    curl 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.

  1. 1
    The same auction, over the sample stores only

    The answer says "mode":"test" and comes from a sample store, with a checkoutToken.

    shell
    curl -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}'
  2. 2
    A practice order

    No card, no charge, no real store is told. The receipt says "Practice order. No money moved."

    shell
    curl -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"}'
  3. 3
    Or connect an agent in test mode
    shell
    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.

  1. 1
    Register the agent with your account key

    You get the agent's own key, once.

    shell
    curl -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}'
  2. 2
    Connect the agent with its own key

    Every order it places is checked against its limits.

    shell
    claude mcp add --transport http calmar "https://calmar.sh/api/mcp?key=THE_AGENT_KEY"
  3. 3
    Get a signed passport for the order it is about to place
    shell
    curl -X POST https://calmar.sh/api/v1/agents/passport \
      -H "Authorization: Bearer THE_AGENT_KEY" -H "Content-Type: application/json" \
      -d '{"checkoutToken":"chk_…"}'
  4. 4
    Anyone can check it
    shell
    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.

  1. 1
    Connect a catalog

    shopify, woocommerce, url, csv or json. The first call returns your store's API key.

    shell
    curl -X POST https://calmar.sh/api/connect -H "Content-Type: application/json" \
      -d '{"sellerRef":"store_123","source":"url",
           "url":"https://anystore.com/products/thing"}'
  2. 2
    Set what you pay to win an order

    And, if you like, a discount for the buyer.

    shell
    curl -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}'
  3. 3
    Your orders: mark shipped, approve refunds
    shell
    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/search

    One 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/procure

    Run the catalog auction. Returns the winner, alternatives and a checkoutToken. Not for flights or hotels.

  • POST/api/v1/checkout

    Place 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/orders

    JSON 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/earnings

    Pending, available, paid and reversed earnings for your key.

  • GET/api/v1/payouts

    Balance and whether a bank account is connected.

  • POST/api/v1/payouts

    action: connect (link a bank account) or withdraw.

  • GET/api/v1/links

    Your buyer links and whether each has a card saved.

  • POST/api/v1/links

    Create a buyer link. Send label, get back url and buyerRef.

Agents

  • GET/api/v1/agents

    Your registered agents, what each spent today, and your account standing.

  • POST/api/v1/agents

    Register an agent: name, and optionally maxPerOrderUsd, dailyCapUsd, verticals. Returns the agent's own key once.

  • PATCH/api/v1/agents

    Change an agent's limits, set status to paused, active or revoked, or send newKey: true to replace its key.

  • POST/api/v1/agents/passport

    Called with an agent's key. A signed passport, valid ten minutes; add checkoutToken to bind it to one order.

  • POST/api/v1/agents/verify

    Check a passport. Public. Also tells you if the agent has been paused or revoked since.

  • GET/api/v1/agents/jwks

    The public key passports are signed with, to check one yourself.

Stores

  • POST/api/connect

    Import a catalog: shopify, woocommerce, url, csv, json.

  • GET/api/v1/bids

    A store's current bid and rebate.

  • POST/api/v1/bids

    Set bidPerOrderUsd, bidPct, rebatePct.

  • GET/api/sales?sellerRef=…

    Orders a store won, with shipping addresses.

Test suppliers

  • POST/api/v1/travel/search

    Test 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/book

    Test 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/search

    Test 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/buy

    Test 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/status

    Test mode only. Poll a Zinc order. Placement finishes after the buy call.

Keys

  • POST/api/keys

    Self-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.

EndpointPer addressPer keyAll callers
POST /api/v1/understand (the playground agent's model call)20 per minute, 300 per daynone600 per minute, 20,000 per day
POST /api/v1/procure60 per minute, 2,000 per day60 per minutenone
POST /api/v1/checkout20 per minute, 300 per day20 per minutenone
Requests made with the playground console's visitor key, on top of the endpoint's own limit30 per minute, 600 per day30 per minute1,200 per minute
POST /api/v1/playground/key10 per minute, 100 per daynone600 per minute
POST /api/v1/search20 per minute, 500 per day120 per minutenone
POST /api/v1/retail/search and /travel/search20 per minute, 500 per day30 per minutenone
POST /api/v1/retail/buy and /travel/book10 per minute10 per minutenone
POST /api/v1/retail/status30 per minute, 600 per day60 per minutenone
Live flight prices behind the flight_search tool. Over it, cached fares are shown20 per minute, 200 per daynone3,000 per day
The MCP endpoint, /api/mcp. Each tool also counts against the limit of its REST twin120 per minute120 per minutenone
POST /api/connect30 per minute, 200 per day30 per minutenone
POST /api/connect with source: url, on top of the limit above10 per minute, 100 per day30 per minute300 per minute, 2,000 per day
POST /api/partners/preview12 per minute, 200 per daynonenone
POST /api/keys20 per minutenonenone
POST /api/billing20 per minutenonenone
429 response
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 money
  1. settled
  2. refund_requested
  3. refunded
shipStatusthe package
  1. none
  2. shipped
  3. in_transit
  4. delivered
earningsyour share
  1. pending
  2. available
  3. paid
  4. reversedon 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.