OpenFacet offers free, real-time access to natural GIA-certified round diamond prices via a structured JSON API. Data includes current DCX index, per-carat matrices, market depth across clarity/color bands, and fancy-shape L/W ratio adjustment models. Unlike closed or credentialed platforms, OpenFacet provides open, unauthenticated, and machine-ready data feeds without account setup or XML legacy formats.

The API supports valuation, algorithmic pricing, and liquidity modeling by exposing core components of OpenFacet’s transparent pricing methodology. All responses are JSON-formatted and timestamped in UTC.

If you prefer spreadsheet workflows, see CSV Data in Google Sheets & Excel for direct CSV imports and pricing formulas based on carat, color, and clarity.

Last updated: August 30, 2026

REST API Endpoints

Endpoints are served from: https://data.openfacet.net/.

GET /matrix.json – Price Matrices

Returns per-carat log price matrices across clarity and color, grouped by fixed carat bands.

Example: /matrix.json

Key Fields

l: Map of carat band → flat array of $\log(\text{per-carat price})$ values. Each array is of length rows × cols, where:
- rows = number of color grades (r)
- cols = number of clarity grades (c)
c: Clarity grade list (columns)
r: Color grade list (rows)
s: Shape [rows, cols] = [len(r), len(c)]

Price Calculation

To compute per-carat price:

$$ \text{price} = \exp(\log_\text{price}) $$

To interpolate $\log(\text{per-carat price})$ for non-discrete carat weights:

$$ \log_i = (1 - \lambda) \cdot \log(p_1) + \lambda \cdot \log(p_2) $$

Where:

$p_1, p_2$ are per-carat prices at carat bands $c_1, c_2$
$\lambda = \frac{c - c_1}{c_2 - c_1}$, with $c$ the target carat

After interpolation, apply Math.exp(log_i) to obtain the interpolated per-carat price.

GET /ratio_models.json – Fancy-Shape L/W Ratio Models

Returns the shape-specific length-to-width ratio adjustment models used for fancy-shape pricing. This endpoint does not replace the base matrix endpoints. Instead, it provides an additional multiplicative layer that is applied on top of a base per-carat price from matrix.json or the cushion matrix dataset when the selected shape is mapped to that source.

Example: /ratio_models.json

Purpose

For shapes such as oval, pear, radiant, emerald, marquise, heart, and cushion, pricing depends not only on carat, color, and clarity, but also on outline proportions. ratio_models.json exposes the calibration data behind that L/W ratio adjustment.

Structure

Top-level shape models are stored under:

shapes[shape_key]

Each shape entry may contain:

dataSource: base matrix family to apply first. Current consumers switch to matrix_cushion.json when this field is cushion; otherwise they use matrix.json.
valueMode: interpretation of the fitted ratio value.
- delta_pct → convert to multiplier as $1 + \frac{v}{100}$
- any other mode → convert to multiplier as $\frac{v}{100}$
slider: UI guidance for acceptable ratio input range
- min: minimum supported ratio
- center: default or neutral ratio
- max: maximum supported ratio
bands[]: carat-band-specific ratio models
- minCarat: inclusive lower bound
- maxCarat: inclusive upper bound when present; open-ended when omitted
- points[]: anchor points for interpolation
  - ratio: L/W ratio anchor
  - value: fitted value at that ratio anchor

Schematic Example

{
  "shapes": {
    "oval": {
      "dataSource": "round",
      "valueMode": "delta_pct",
      "slider": {
        "min": 1.20,
        "center": 1.45,
        "max": 1.75
      },
      "bands": [
        {
          "minCarat": 0.3,
          "maxCarat": 0.69,
          "points": [
            { "ratio": 1.25, "value": -3.2 },
            { "ratio": 1.40, "value": 0.0 },
            { "ratio": 1.55, "value": 2.1 }
          ]
        }
      ]
    }
  }
}

How to Apply It

Compute the base per-carat price from the appropriate matrix dataset.
Select the matching shape model under shapes.
Find the active entry in bands[] for the target carat.
Linearly interpolate the value between the two surrounding points[] by ratio.
Convert that interpolated value into a multiplier using valueMode.
Multiply the base per-carat price by that multiplier.

In compact form:

$$ P_{\text{final}} = P_{\text{base}} \cdot M(r) $$

Where $M(r)$ is the interpolated L/W ratio multiplier for the chosen shape and carat band.

Out-of-Range Handling

Consumers should avoid unconstrained extrapolation. When a ratio falls outside the modeled anchor range for a band, the practical implementation clamps to the nearest supported endpoint and may treat the result as more preference-driven than tightly market-calibrated.

GET /index.json – Composite Index & Basket

Returns the current Diamond Composite Index (DCX) and a representative basket of actively traded specifications.

Example: /index.json

Sample Response

{
  "dcx": 3568.6,
  "specs": [
    {
      "carat": 0.5,
      "clarity": "SI1",
      "color": "H",
      "cut": "Excellent",
      "log": 7.428,
      "per_carat": 1682.38,
      "price": 841.19,
      "weight": 0.22
    },
    ...
  ],
  "trend": 0.13,
  "ts": "2025-05-19T13:26:49Z"
}

Fields

dcx: Composite per-carat price in USD.
specs[]: Sample stones with:
- price: Total price in USD
- per_carat: USD per carat
- log: $\log(\text{price})$ for interpolation
- weight: Basket contribution
trend: 24h change in dcx, in percent (e.g. 0.13 = +0.13%)
ts: Timestamp in ISO 8601 format

GET /depth.json – Market Depth

Reports inventory depth across dimensions of carat, color, and clarity. Useful for liquidity-aware models or filtering.

Example: /depth.json

Structure

clarity[carat][clarity]: Listings count per clarity grade at given carat
color[carat][color]: Listings count per color grade at given carat
colclar[color][clarity]: Total listings for each color × clarity pair
ts: Snapshot timestamp

Example

"1.0": {
  "VS2": 1232
}

There are 1232 listings for 1.0ct VS2 diamonds at the snapshot time.

MCP Server

The same diamond pricing data is also exposed through a Model Context Protocol (MCP)-compliant remote server at https://mcp.openfacet.net/ for AI agents and LLM applications. It can also be connected directly to ChatGPT as a plugin (see ChatGPT Plugin demo & query examples). The server uses streamable HTTP and MCP protocol version 2026-07-28.

This remote MCP endpoint provides programmatic access to:

Interpolated diamond prices (get_diamond_price): real-time pricing across carat, color, clarity, shape, and L/W ratio
DCX index values (get_dcx_index): the composite index with 24-hour, 7-day, and 30-day trends
Market depth analytics (get_market_depth): comparable observed-offer counts by carat, color, and clarity

Discovery and Health

GET /.well-known/mcp.json returns the server manifest, available tools, and the streamable HTTP endpoint. GET /health returns the service status and supported MCP protocol version.

The root URL accepts MCP POST requests. A browser GET request to the root redirects to this documentation page.

Request Requirements

The server is unauthenticated. Every JSON-RPC request must include request metadata in params._meta and matching HTTP headers:

MCP-Protocol-Version: 2026-07-28
Mcp-Method: the JSON-RPC method, such as tools/call
Mcp-Name: the tool name for tools/call, such as get_diamond_price
params._meta.io.modelcontextprotocol/protocolVersion: "2026-07-28"
params._meta.io.modelcontextprotocol/clientCapabilities: an object describing client capabilities; {} is valid

Call initialize first to negotiate the protocol version and retrieve the server information and capabilities. server/discover advertises supported protocol versions and capabilities; then use tools/list to retrieve the tool schemas. Discovery and tool-list responses declare a public cache lifetime of 24 hours.

Unknown JSON-RPC methods return HTTP 404. Invalid parameters, unsupported protocol versions, and request header/body mismatches return HTTP 400; successful tool calls and JSON-RPC errors not covered by those cases return HTTP 200.

Example

Requesting a diamond price quote for a 1.23ct G VS2 round diamond:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientCapabilities": {}
    },
    "name": "get_diamond_price",
    "arguments": {
      "carat": 1.23,
      "color": "G",
      "clarity": "VS2"
    }
  }
}

Send the request with these headers:

Content-Type: application/json
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/call
Mcp-Name: get_diamond_price

The response has resultType: "complete", human-readable content, machine-readable structuredContent, and server information in _meta. A price response includes the normalized specifications, per-carat and total USD prices, a tracking URL, and, for fancy shapes, supported and observed L/W ratio ranges plus whether the selected ratio is preference-driven.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "resultType": "complete",
    "content": [{ "type": "text", "text": "OpenFacet diamond price quote..." }],
    "structuredContent": {
      "shape": "round",
      "carat": 1.23,
      "color": "G",
      "clarity": "VS2",
      "shape_ratio": 1,
      "per_carat_usd": 4490,
      "total_usd": 5523,
      "tracking_url": "https://openfacet.net/en/my-diamond/?..."
    },
    "_meta": {
      "timestamp": "2026-08-08T00:00:00.000Z",
      "source": "openfacet.net",
      "io.modelcontextprotocol/serverInfo": {
        "name": "openfacet-diamond-pricing",
        "version": "2.0.0"
      }
    }
  }
}

Tool Inputs

get_diamond_price requires carat from 0.3 through 6.0, a color from D through M, and a clarity from FL, IF, VVS1, VVS2, VS1, VS2, SI1, or SI2. It optionally accepts shape (round, cushion, radiant, emerald, oval, pear, marquise, or heart) and shape_ratio. When no ratio is supplied, the shape model center is used. The response reports the usable ratio ranges and clamps preference-driven ratios to the nearest observed pricing endpoint.

get_dcx_index takes no arguments and returns the index, its 24-hour, 7-day, and 30-day trends, and its market basket. get_market_depth accepts an optional carat from 0.3 through 6.0; without it, the tool returns available carat points and the top observed color/clarity combinations.

For developers integrating with AI systems, the MCP server provides the same underlying datasets as the REST endpoints above, with interpolation, shape-ratio adjustment, and an interface designed for LLM tool use.

Data Freshness

Snapshots are updated periodically, typically once per 24h. Check the ts field in each response to ensure data recency. MCP tool responses are based on the same underlying snapshot datasets.

For methodology details, see the OpenFacet & DCX Methodology page.

Disclaimer: The Diamond Composite Index (DCX) is a model-based benchmark constructed from public retail listings. It does not represent executable prices or financial advice. All data is filtered, interpolated, and smoothed for index use. Use at your own discretion. GIA is a registered trademark of the Gemological Institute of America. This site is not affiliated with, endorsed by, or associated with GIA.

Real-Time Diamond Pricing API

REST API Endpoints

GET /matrix.json – Price Matrices

Key Fields

Price Calculation

GET /ratio_models.json – Fancy-Shape L/W Ratio Models

Purpose

Structure

Schematic Example

How to Apply It

Out-of-Range Handling

GET /index.json – Composite Index & Basket

Sample Response

Fields

GET /depth.json – Market Depth

Structure

Example

MCP Server

Discovery and Health

Request Requirements

Example

Tool Inputs

Data Freshness