From a7014b0795141408162e9474c12e11854b39a3f3 Mon Sep 17 00:00:00 2001
From: Tidelight Mirror Bot <tidelight-mirror-bot@users.noreply.github.com>
Date: Fri, 16 Oct 2026 02:11:21 +0000
Subject: [PATCH] chore(sync): mirror api from
 8b8e01c2fc176b8c362acfc351502478f5d28d06

---
 README.md               | 4 ++--
 openapi/tidelight.yaml  | 4 ++++
 tests/contract.test.mjs | 1 +
 3 files changed, 7 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index e249255..90e5b12 100644
--- a/README.md
+++ b/README.md
@@ -6,7 +6,7 @@ The live, versioned REST API is at `https://api.tidelight.app/v1`. The OpenAPI 3
 
 | Operation | Scope | Purpose |
 | --- | --- | --- |
-| `GET /market/instruments` | `market:read` | List supported Reality tokenized-equity spot instruments |
+| `GET /market/instruments` | `market:read` | List supported Reality tokenized-equity spot instruments; optionally filter by `underlying_ticker` before pagination |
 | `POST /research/jobs` | `research:run` | Start an asynchronous, idempotent company snapshot |
 | `GET /research/jobs/{job_id}` | `research:run` | Read status/result within the key's project |
 | `DELETE /research/jobs/{job_id}` | `research:run` | Cancel queued work or request cancellation |
@@ -23,7 +23,7 @@ export TIDELIGHT_API_KEY='tl_test_…'
 curl --fail-with-body \
   -H "Authorization: Bearer $TIDELIGHT_API_KEY" \
   -H 'Accept: application/json' \
-  'https://api.tidelight.app/v1/market/instruments?kind=rtoken&limit=10'
+  'https://api.tidelight.app/v1/market/instruments?kind=rtoken&underlying_ticker=AAPL&limit=10'
 ```
 
 Responses include a request ID and market provenance, including the provider source and timestamp. rToken spot instruments are tokenized products; they are not underlying shares or stock perpetual contracts. An unavailable provider returns a safe service error instead of fabricated values. Async research responses include a job ID; reuse the same `Idempotency-Key` when retrying a start request.
diff --git a/openapi/tidelight.yaml b/openapi/tidelight.yaml
index a887986..dd3ad52 100644
--- a/openapi/tidelight.yaml
+++ b/openapi/tidelight.yaml
@@ -22,6 +22,10 @@ paths:
         - name: limit
           in: query
           schema: { type: integer, minimum: 1, maximum: 100, default: 20 }
+        - name: underlying_ticker
+          in: query
+          description: Filter Reality spot instruments by their underlying US stock ticker before pagination.
+          schema: { type: string, pattern: '^[A-Za-z][A-Za-z0-9.]{0,9}$' }
         - name: cursor
           in: query
           schema: { type: string, pattern: '^[A-Z0-9]{2,32}$' }
diff --git a/tests/contract.test.mjs b/tests/contract.test.mjs
index d9636d2..2d132bc 100644
--- a/tests/contract.test.mjs
+++ b/tests/contract.test.mjs
@@ -42,6 +42,7 @@ test("contract preserves async idempotency and distinct financial instrument pro
   assert.equal(schemas.Instrument.properties.instrument_type.const, "tokenized_equity_spot");
   assert.equal(schemas.StockPerpetual.properties.instrument_type.const, "stock_perpetual");
   assert.notEqual(schemas.Instrument.properties.source.const, schemas.StockPerpetual.properties.source.const);
+  assert.equal(spec.paths["/market/instruments"].get.parameters.find(parameter => parameter.name === "underlying_ticker")?.schema.pattern, "^[A-Za-z][A-Za-z0-9.]{0,9}$");
 });
 
 test("webhook secrets are documented as one-time output and excluded from list schema", () => {