Partner Trading API
Connect your business to Cru’s fine wine market. Read both sides of the book, place and manage bids, list wine for sale, and follow your portfolio and trades — over one versioned REST API, or from an AI assistant through Cru’s MCP server.
Read the market
39 live endpoints across 10 groups, each with parameters, fields, and PHP and Python examples.
TRADINGBid, list and confirm
How a write runs for a partner, made safe to retry with a reference, and for a connected app, confirmed by the customer.
MCPUse Cru from an assistant
27 tools for Claude, ChatGPT and other MCP clients, signed in with the customer’s own Cru account.
CODEStart building
Cru’s SDKs for PHP, Go and Python, the Postman collection, and a first request without either.
Your first integration
Get your API credentials
Ask Cru for a client key and secret with the scopes you need — meta:read and market:read to read the market, bids:write to place bids. Confirm your environment and permitted markets.
Check your connection
Call GET /ping to verify your credentials, granted scopes, market and currency.
Read the market, then act on it
Page through GET /market/bids and GET /market/offers, then place a bid with POST /bids — with a reference, so a retry can never place it twice.
1 / 4Every request carries CLIENT-KEY and CLIENT-SECRET. GET /ping answers with the account, market, currency and scopes they carry.
The request sequence, end to end
6 STEPSYour server
Confirm what your credentials can do
GET /pingOne authenticated call that returns your account, market, currency, granted scopes and the credential’s expiry, and no trading data at all. Run it in your setup checks.
KEEP
client.scopes, client.currencyYour server
Find the wine
GET /winesSearch by name to get its LWIN18 — wine, vintage and pack in one 18-digit code — which every other endpoint takes.
KEEP
lwin18Your server
Read both sides of the market
GET /market/offers/market/offers is what the wine costs to buy, gross; /market/bids is what it would sell for, net of commission. Prices are decimal amounts in the market’s currency.
KEEP
price, codeYour server
Place a bid, with a reference you generated first
POST /bidsA partner credential’s write executes at once. Store the reference before sending: it is what makes the request safe to repeat.
KEEP
reference, data.bid.codeCru
A repeat is replayed, never placed twice
If the call times out, send it again unchanged. Cru answers with the first outcome and Idempotent-Replayed: true — or 409 REQUEST_IN_PROGRESS while the first is still running.
Your server
Follow it until it fills
GET /bidsPoll your bid by code or client_ref: quantity_matched rises as sellers fill it, and what you bought appears in /trades/purchases with its order number.
KEEP
status, quantity_matched
Partners and connected apps
The API serves two kinds of caller. A partner integrates server-to-server with a client key and secret Cru issues, and its writes execute at once. A connected app — an AI assistant, a portfolio tool — acts for one Cru customer with a token the customer approved, and every trade it prepares waits for the customer’s yes. Which are you? →
Webhooks are reserved and not built, so changes are read by polling.