ALT/FNDATA Data API

Recommended path for new developers

Follow these steps to go from zero to a working integration.

Build with the API

Available datasets

Access is granted per API key — your key may authorize a subset of these tables.

Tools & Integrations

Authentication #

All endpoints except /v1/health require an API key. Pass your key in the X-API-Key header:

X-API-Key: afi_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Available Tables #

Eighteen datasets are available. Use the /v1/tables/{name}/schema endpoint to see all columns for any table. Access is granted per API key — your key may authorize a subset.

watches

handbags

jewelry

gems

automobile

motorcycle

aircraft

wine_whisky

Endpoints #

The API exposes five endpoints. Replace {name} with any of the datasets listed above. Availability depends on which tables your API key authorizes.

GET /v1/health

curl https://api.altfndata.com/v1/health

{
  "status": "healthy",
  "version": "1.0.0",
  "timestamp": "2026-03-04T13:00:00.000000+00:00",
  "athena_database": "altfinancedb"
}

GET /v1/tables

curl -H "X-API-Key: YOUR_KEY" https://api.altfndata.com/v1/tables

{
  "tables": [
    {"name": "watches",     "description": "Luxury watch auction results",         "column_count": 66},
    {"name": "handbags",    "description": "Luxury handbag auction results",       "column_count": 50},
    {"name": "jewelry",     "description": "Jewelry and gemstone auction results", "column_count": 57},
    {"name": "gems",        "description": "Gemstone auction results",             "column_count": 58},
    {"name": "automobile",  "description": "Collector car auction results",        "column_count": 60},
    {"name": "motorcycle",  "description": "Collector motorcycle auction results", "column_count": 48},
    {"name": "aircraft",    "description": "Aircraft auction results",             "column_count": 84},
    {"name": "wine_whisky", "description": "Wine and whisky auction results",      "column_count": 45}
  ]
}

Only tables authorized for your key appear in the response.

GET /v1/tables/{name}/schema

curl -H "X-API-Key: YOUR_KEY" https://api.altfndata.com/v1/tables/watches/schema

{
  "table": "watches",
  "columns": [
    {"name": "item_title", "type": "string"},
    {"name": "designer", "type": "string"},
    {"name": "usd_price_decimal", "type": "double"},
    {"name": "sale_date", "type": "string"}
  ]
}

Querying Data #

POST /v1/tables/{name}/query (recommended)

Full control over field selection, filters, sorting, and pagination.

Request body

{
  "fields": ["item_title", "designer", "usd_price_decimal", "sale_date", "vendor"],
  "filters": [
    {"field": "designer", "op": "eq", "value": "Rolex"},
    {"field": "usd_price_decimal", "op": "gte", "value": 50000}
  ],
  "sort": [
    {"field": "usd_price_decimal", "direction": "desc"}
  ],
  "limit": 20,
  "offset": 0
}

FilterItem

{"field": "column_name", "op": "eq", "value": "some_value"}

SortItem

{"field": "column_name", "direction": "desc"}

Response

{
  "table": "watches",
  "query_execution_id": "ae3d3e58-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "execution_time_ms": 1505,
  "result_count": 5,
  "limit": 20,
  "offset": 0,
  "fields": ["item_title", "designer", "usd_price_decimal", "sale_date", "vendor"],
  "data": [
    {
      "item_title": "Ref.6239, Cosmograph Daytona \"Paul Newman\"",
      "designer": "Rolex",
      "usd_price_decimal": 17752500.0,
      "sale_date": "-",
      "vendor": "Phillips"
    }
  ]
}

GET /v1/tables/{name}/query (simplified)

For simple queries, use URL parameters:

curl -H "X-API-Key: YOUR_KEY" \
  "https://api.altfndata.com/v1/tables/watches/query?designer=Rolex&limit=5&sort=usd_price_decimal:desc"

Pagination

Use limit and offset to page through results:

Page 1: limit=100&offset=0
Page 2: limit=100&offset=100
Page 3: limit=100&offset=200

When result_count < limit, you've reached the last page.

Filter Operators #

All filters use the "op" key. Multiple filters are AND-ed together.

Values for numeric operators (gt, gte, lt, lte) are auto-cast to double.

Valuation API #< 🎨

Fine Art

49 columns · 4,069,580 records

Fine art auction results across all movements and periods

🏹

Works of Art

42 columns · 4,805,673 records

Works of art with stone/jewelry relevance (jade, jadeite, diamond-set, etc.)

🛍

Design

56 columns · 1,848,300 records

Design and decorative arts — furniture, lighting (incl. Tiffany Studios lamps), glass, ceramics, and...

📘

Books

41 columns · 778,310 records

Books, manuscripts, maps and printed material.

🪙

Coins

45 columns · 308,810 records

Numismatic coin auction results.

🛠

Automobilia

41 columns · 254,450 records

Automobilia — automotive memorabilia, parts, signage, models and related collectibles (not the cars themselves;...

👗

Fashion

42 columns · 236,655 records

Fashion and couture — clothing and accessories (not handbags or shoes, which have their own tables).

👞

Shoes

43 columns · 15,925 records

Footwear — designer shoes and collectible sneakers.

🛣

Other Automobile

38 columns · 11,387 records

Other vehicles -- non-car, non-motorcycle (boats, tractors, trucks, buses, military).

🌊

Perfume

39 columns · 4,900 records

Perfume and collectible fragrance bottles / flacons.

👕

Accessories

56 columns · 38,147 records

Fashion accessories -- belts, scarves, cufflinks, brooches, sunglasses (incl. gem-set pieces).

🎻

Musical Instruments

31 columns · 16,611 records

Musical instruments -- guitars, violin family, pianos and keyboards, woodwind, brass, percussion, amplifiers.

/h2>

The Valuation API returns a valuation and the comparable sales that support it for a luxury or collectible item. You send an item's attributes; we return a price range, a confidence score, and the comps behind it. The dataset stays on our side, so you receive the answer and supporting comparables rather than raw records. Valuation is included on Professional and above plans, so your existing API key carries it, with no separate key required. It is metered separately from your data row quota, where one valuation counts as one unit.

Method	Path	Auth	Description
POST	/v1/valuation	Yes	Value an item and return supporting comps
POST	/v1/valuation/batch	Yes	Value up to 25 items in one call
GET	/v1/valuation/history	Yes	Median price over time for a brand and model
GET	/v1/valuation/liquidity	Yes	Sell-through and buy-in rate for a brand and model
GET	/v1/valuation/adjustments	Yes	Value by attribute (hardware, material) vs the model baseline
GET	/v1/valuation/forecast	Yes	Projected value trajectory from auction history
GET	/v1/valuation/models	Yes	List models we can value for a brand

POST /v1/valuation

Send structured attributes (recommended) or a lot URL / free-text description in input. More attributes yield a tighter comp set.

curl https://api.altfndata.com/v1/valuation \
  -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"category":"handbags","brand":"Herm\u00e8s","model":"Birkin 25","material":"togo","hardware":"gold","color":"black"}'

{
  "ok": true,
  "category": "handbags",
  "query": { "brand": "Herm\u00e8s", "model": "Birkin 25", "size": "25", "material": "leather", "hardware": "gold", "color": "black" },
  "valuation": { "median": 23999, "low": 12567, "high": 52324, "p25": 18000, "p75": 30000, "count": 529, "currency": "USD" },
  "confidence": "high",
  "confidence_score": 0.99,
  "comps": [
    { "vendor": "Sotheby's", "sale_date": "2026-01-14", "usd_price": 24000, "model": "Birkin 25", "material": "leather", "lot_url": "https://..." }
  ]
}

Valuations are in USD. median is the headline figure, low/high the range, p25/p75 the interquartile band, and count the number of comparable sales used. confidence is low, medium or high; confidence_score runs 0 to 1. comps are the supporting comparable sales, licensed for display. If there are too few comparables, ok is false with a reason. When available, price_history gives the median-by-year series with a direction and percentage change. When an asking_price was supplied, verdict reports whether it is below, in line with, or above the market, with the difference against the median.

POST /v1/valuation/batch

Value many items in one call. items is an array where each entry takes the same fields as a single valuation. Up to 25 items per call. Each valuation is metered as one unit; a bad item is returned as ok: false with an error rather than failing the batch.

curl https://api.altfndata.com/v1/valuation/batch \n  -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \n  -d '{"items":[{"brand":"Hermès","model":"Birkin 25"},{"brand":"Chanel","model":"Classic Flap Medium"}]}'

Returns { "count", "valued", "results": [ ... ] }, one result per item in order.

GET /v1/valuation/history

Median price over time for a brand and model, for charting a value trajectory without running a full item valuation. Returns the current valuation summary plus a median-by-year series. Metered as one call.

curl "https://api.altfndata.com/v1/valuation/history?brand=Hermès&model=Birkin%2025&category=handbags" \n  -H "X-API-Key: YOUR_KEY"

GET /v1/valuation/liquidity

Sell-through and buy-in rate for a brand and model: of the lots offered at auction, the share that sold. Marketplace listings and withdrawn or unconfirmed lots are excluded, so this reflects auction demand. Returns sell_through_rate, buy_in_rate, and the underlying sold / unsold / offered counts. Below a small sample, the rate is null with a note.

curl "https://api.altfndata.com/v1/valuation/liquidity?brand=Hermès&model=Birkin&category=handbags" \n  -H "X-API-Key: YOUR_KEY"

GET /v1/valuation/adjustments

How value shifts by attribute for a brand and model: the median for each hardware and material, expressed as vs_baseline_pct against the model's overall median. The appraiser view of what each feature is worth. Handbags for now.

curl "https://api.altfndata.com/v1/valuation/adjustments?brand=Hermès&model=Birkin&category=handbags" \n  -H "X-API-Key: YOUR_KEY"

GET /v1/valuation/forecast

Projects a model's median value forward from its auction history, with a confidence band. horizon is 1 to 5 years (default 3). Returns the historical CAGR and volatility alongside the projection. This is a trend estimate, not a guarantee.

curl "https://api.altfndata.com/v1/valuation/forecast?brand=Hermès&model=Birkin&horizon=3" \n  -H "X-API-Key: YOUR_KEY"

GET /v1/valuation/models

Lists the models we can value for a brand. Item identification is attribute-based; there is no fixed catalogue of item IDs. This returns the models with enough comparable sales to value.

curl "https://api.altfndata.com/v1/valuation/models?brand=Herm\u00e8s&category=handbags" \
  -H "X-API-Key: YOUR_KEY"

Rate Limits #

Usage limits vary by subscription tier.

Quotas are enforced per table: the daily cap resets at midnight UTC, and the monthly cap resets on the 1st (UTC). Valuations are metered separately against your plan's valuation allowance, one unit per valuation.

When limits are exceeded, you receive HTTP 429:

{"detail": "Rate limit exceeded (30 requests/minute). Try again later."}

{"detail": "Daily row quota exceeded for watches (10,000 rows/day). Resets at midnight UTC."}

{"detail": "Monthly row quota exceeded for watches (150,000 rows/month). Resets on the 1st (UTC)."}

Error Handling #

Code Examples #

curl

# List tables
curl -H "X-API-Key: YOUR_KEY" https://api.altfndata.com/v1/tables

# Simple GET query
curl -H "X-API-Key: YOUR_KEY" \
  "https://api.altfndata.com/v1/tables/watches/query?designer=Rolex&limit=10&sort=usd_price_decimal:desc"

# POST query with filters
curl -X POST https://api.altfndata.com/v1/tables/watches/query \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": ["item_title", "designer", "vendor", "usd_price_decimal", "sale_date"],
    "filters": [
      {"field": "designer", "op": "eq", "value": "Rolex"},
      {"field": "usd_price_decimal", "op": "gte", "value": 50000}
    ],
    "sort": [{"field": "usd_price_decimal", "direction": "desc"}],
    "limit": 20
  }'

Python

import requests

API_KEY = "YOUR_KEY"
BASE = "https://api.altfndata.com"
HEADERS = {"X-API-Key": API_KEY}


# List tables
tables = requests.get(f"{BASE}/v1/tables", headers=HEADERS).json()
for t in tables["tables"]:
    print(f"{t['name']}: {t['column_count']} columns")


# Get schema
schema = requests.get(f"{BASE}/v1/tables/watches/schema", headers=HEADERS).json()
for col in schema["columns"][:10]:
    print(f"  {col['name']}: {col['type']}")


# Query: Top 10 Rolex watches by price
resp = requests.post(
    f"{BASE}/v1/tables/watches/query",
    headers={**HEADERS, "Content-Type": "application/json"},
    json={
        "fields": ["item_title", "vendor", "usd_price_decimal", "sale_date"],
        "filters": [
            {"field": "designer", "op": "eq", "value": "Rolex"},
            {"field": "usd_price_decimal", "op": "is_not_null"},
        ],
        "sort": [{"field": "usd_price_decimal", "direction": "desc"}],
        "limit": 10,
    },
)
data = resp.json()
print(f"\n{data['result_count']} results ({data['execution_time_ms']}ms)\n")
for row in data["data"]:
    print(f"  ${row['usd_price_decimal']:,.0f}  {row['vendor']}  {row['item_title'][:60]}")


# Pagination
all_results = []
offset = 0
while True:
    resp = requests.post(
        f"{BASE}/v1/tables/watches/query",
        headers={**HEADERS, "Content-Type": "application/json"},
        json={
            "fields": ["item_title", "usd_price_decimal"],
            "filters": [{"field": "designer", "op": "eq", "value": "Patek Philippe"}],
            "sort": [{"field": "usd_price_decimal", "direction": "desc"}],
            "limit": 100,
            "offset": offset,
        },
    )
    page = resp.json()
    all_results.extend(page["data"])
    if page["result_count"] < 100:
        break
    offset += 100

print(f"Total Patek Philippe records: {len(all_results)}")

JavaScript / Node.js

const API_KEY = "YOUR_KEY";
const BASE = "https://api.altfndata.com";

// List tables
const tables = await fetch(`${BASE}/v1/tables`, {
  headers: { "X-API-Key": API_KEY },
}).then((r) => r.json());

console.log(tables);

// Query watches
const resp = await fetch(`${BASE}/v1/tables/watches/query`, {
  method: "POST",
  headers: {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    fields: ["item_title", "designer", "usd_price_decimal", "vendor"],
    filters: [
      { field: "designer", op: "eq", value: "Omega" },
      { field: "usd_price_decimal", op: "gte", value: 10000 },
    ],
    sort: [{ field: "usd_price_decimal", direction: "desc" }],
    limit: 10,
  }),
}).then((r) => r.json());

console.log(`${resp.result_count} results (${resp.execution_time_ms}ms)`);
resp.data.forEach((row) => {
  console.log(`  $${row.usd_price_decimal}  ${row.item_title}`);
});

MCP Server for AI assistants #

The ALT/FNDATA MCP server lets your AI assistant query the API directly in conversation. Instead of writing code, just ask questions in natural language. It uses the open Model Context Protocol (MCP), so it works with Claude, ChatGPT, Gemini, Perplexity and other assistants and developer tools that support MCP servers.

Option 1: Connect the hosted server (no install)

In any assistant that supports remote MCP servers (often called custom connectors), add a connector with this URL:

https://mcp.altfndata.com/mcp

Choose OAuth if you are asked for an authentication method. When you connect, a sign-in page asks for your ALT/FNDATA API key. Get your key from API Key & MCP in the app.

• Claude: Settings → Connectors → add a custom connector.
• ChatGPT: add it as a custom connector (developer mode). ChatGPT only connects to hosted servers, so use this option.
• Perplexity: Settings → Connectors → add a custom connector with the URL above.
• Gemini app: Settings → Connected Apps → add a custom app with the URL above (personal Google accounts).
• Gemini Enterprise: an admin adds ALT/FNDATA once for the organisation. See Gemini Enterprise set-up below.

Menu names and plan availability are set by each assistant and change over time. Check its help pages if the steps differ.

Gemini Enterprise (admin set-up)

Gemini Enterprise connects through a Custom MCP Server data store, which an admin sets up once for the organisation.

1. Register a client. The response contains a client_id and a client_secret. The secret is shown only once, so store it safely.
   bashCopy

   curl -X POST https://mcp.altfndata.com/register \
     -H "Content-Type: application/json" \
     -d '{"client_name": "Gemini Enterprise (your organisation)",
          "redirect_uris": ["https://vertexaisearch.cloud.google.com/oauth-redirect"],
          "token_endpoint_auth_method": "client_secret_post",
          "grant_types": ["authorization_code", "refresh_token"],
          "response_types": ["code"],
          "scope": "read"}'

2. In the Gemini Enterprise console, add a Custom MCP Server data store with these values:

   Field	Value
   MCP Server URL	https://mcp.altfndata.com/mcp
   Authorization URL	https://mcp.altfndata.com/authorize
   Token URL	https://mcp.altfndata.com/token
   Client ID	client_id from step 1
   Client Secret	client_secret from step 1
   Scopes	read
   Enable PKCE	ticked

3. Each user then connects from Gemini and signs in with their own ALT/FNDATA API key. The client ID and secret only identify your organisation's Gemini Enterprise; they give no access to data on their own.

Google's guide to setting up a custom MCP server describes the console screens.

Option 2: Run it locally

For desktop apps and developer tools that launch MCP servers on your machine.

pip install altfinance-mcp

Requires Python 3.10+. Most tools take a configuration in this shape; add it to the tool's MCP settings and restart it:

{
  "mcpServers": {
    "altfinance": {
      "command": "altfinance-mcp",
      "env": {
        "ALTFINANCE_API_KEY": "YOUR_KEY"
      }
    }
  }
}

Example: Claude Desktop

Add the configuration above to the Claude Desktop config file, then restart Claude Desktop:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Example: Claude Code

export ALTFINANCE_API_KEY="YOUR_KEY"
claude mcp add altfinance -- altfinance-mcp

MCP Tools

The server exposes 9 read-only tools. Every tool is annotated readOnlyHint and openWorldHint, and no tool modifies data.

Datasets and fields

The database spans 20 tables. Call list_tables for the live set with current column counts.

gems vs jewelry: gems holds LOOSE, unmounted stones (the right table for a gemstone valuation); jewelry holds FINISHED, mounted pieces set with stones. If one returns nothing, try the other.

Limits and caveats

• Price alerts are read-only over MCP. Alerts and the watchlist belong to a signed-in ALT/FNDATA account (Cognito login), not to an API key. The MCP authenticates with an API key only, so it cannot create or enable alerts, and even reading requires the alerts feed to be reachable, otherwise list_alerts returns setup guidance rather than a feed. Manage alerts in the app at app.altfndata.com. Allowance by plan: free 0, registered 1, collector 10, pro 100, included with Membership.
• Occasional suggestions. Some tool responses may append a single short "💡" line suggesting a complementary product or a plan upgrade. It appears at most once per response, only at a genuine tier boundary (a table your plan does not include, or an exhausted row quota) or as a relevant feature tip, and never for unlimited or comp accounts. It never changes the data returned.
• Percentiles and medians in market_stats and price_trend are computed server-side over the full matching set, not sampled client-side, so they reflect the whole market rather than the rows returned.
• Read-only. Every tool is annotated readOnlyHint; the MCP never writes.

Example Prompts

Once connected, ask your assistant:

• "What tables are available in the ALT/FNDATA database?"
• "Give me market stats for Rolex Daytona watches"
• "How have Hermes Birkin prices moved by year?"
• "Price-check a Rolex Daytona 116500 white dial"
• "Search the whole market for a Burma ruby ring over $50k"
• "What loose sapphires have sold at auction?" (this uses gems, not jewelry)

The assistant calls the right tools, handles schemas, and formats the results.

Environment Variables