feat: add /scripts/{script_hash}/utxos endpoint

[slowbackspace]

Summary

Adds a new paged endpoint GET /scripts/{script_hash}/utxos that lists the UTXOs holding a given script as a reference script (CIP-33).

Motivation

From a support ticket: to use a script as a reference input (CIP-31) you need the tx_hash#output_index of a UTXO carrying it. Today the only way via Blockfrost is to know the holding address and enumerate its UTXOs — awkward, since a script can be deployed at many addresses (or unknown ones). This endpoint resolves a script hash directly to the UTXOs that carry it.

A script can legitimately be held by multiple unspent UTXOs (observed up to 24 on mainnet), so the endpoint is paginated.

Response shape

Mirrors /addresses/{address}/utxos so clients can reuse existing UTXO parsing, but omits the deprecated tx_index field — consistent with the newer tx_content_utxo schema, which only exposes output_index.

Changes

• src/schemas/scripts/script_utxos.yaml — new response schema
• src/paths/api/scripts/{script_hash}/utxos.yaml — new path
• registered in src/definitions.yaml
• version bump 0.1.89 → 0.1.90
• regenerated bundles, types, json-schema, snapshot

Notes

• The matching backend implementation (blockfrost-backend-ryo) depends on this version once published.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
openapi	Ready	Preview, Comment	Jun 23, 2026 12:29pm

[Copilot]

Pull request overview

Adds a new Cardano Scripts API endpoint to discover UTXOs that carry a given script as a reference script (CIP-33), enabling clients to locate tx_hash#output_index without enumerating addresses.

Changes:

• Added GET /scripts/{script_hash}/utxos path with standard pagination params (count, page, order).
• Introduced a new script_utxos response schema (mirroring address UTXO responses but without deprecated tx_index).
• Bumped version 0.1.89 → 0.1.90 and regenerated bundled specs/types/snapshots/docs.

Reviewed changes

Copilot reviewed 11 out of 12 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
test/tests/snapshots/get-schema-for-endpoint.test.ts.snap	Snapshot updated to include the new endpoint schema.
src/schemas/scripts/script_utxos.yaml	New response schema for script reference UTXO listing.
src/paths/api/scripts/{script_hash}/utxos.yaml	New OpenAPI path definition for listing reference-script-holding UTXOs.
src/generated-types.ts	Regenerated TS types including the new path and schema.
src/definitions.yaml	Registered the new path and bumped version.
package.json	Package version bump to 0.1.90.
openapi.yaml	Regenerated OpenAPI YAML bundle including new path/schema and version bump.
openapi.json	Regenerated OpenAPI JSON bundle including new path/schema and version bump.
docs/blockfrost-openapi.yaml	Regenerated docs bundle including new path/schema and version bump.
CHANGELOG.md	Added release entry for 0.1.90 documenting the new endpoint.
blockfrost-openapi.yaml	Regenerated bundled spec including new path/schema and version bump.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 12 changed files in this pull request and generated no new comments.