Sign in

v1

latestOpenAPI 3.0.0MPL-2.02026-07-17153889.2 KB
Matches

Get Matches (*)

Retrieve matches from the database matching the given pattern, in descending slot_no order. Results are streamed to the client for more efficiency. See Patterns for more information about constructing patterns.

get/matches/{pattern}

Path parameters

'*' required
OR
OR
string required
  ┏━━━━━━━━━━━┓ ╭───╮ ┏━━━━━━━━━━━━┓
╾─┫ POLICY_ID ┣─┤ . ├─┫ ASSET_NAME ┣─╼
  ┗━━━━━━━━━━━┛ ╰───╯ ┗━━━━━━━━━━━━┛

A policy id (base16-encoded) and an optional asset name (base16-encoded), dot-separated.

Examples:

  • 1220099e5e430475c219518179efc7e6c8289db028904834025d5b086.*
  • 1220099e5e430475c219518179efc7e6c8289db028904834025d5b086.08661220099e
OR
string required
  ┏━━━━━━━━━━━━━━┓ ╭───╮ ┏━━━━━━━━━━━━━━━━┓
╾─┫ OUTPUT_INDEX ┣─┤ @ ├─┫ TRANSACTION_ID ┣─╼
  ┗━━━━━━━━━━━━━━┛ ╰───╯ ┗━━━━━━━━━━━━━━━━┛

An (optional) output index and transaction id (base16-encoded), separated by a @.

Examples:

  • 42@35d8340cd6a5d31bf9d09706b92adedf9b1b632e682fdab9fc8865ee3de14e09
  • *@35d8340cd6a5d31bf9d09706b92adedf9b1b632e682fdab9fc8865ee3de14e09

A matching pattern on addresses, assets or transactions.

See Patterns for more details.

Query parameters

A query flag (i.e. ?resolve_hashes) to resolve hash references and include datum and script when available.

A query flag (i.e. ?spent) to filter matches by status, to get only 'spent' matches. Note that, when running kupo with --prune-utxo, this will always return an empty list of results.

A query flag (i.e. ?unspent) filter matches by status, to get only 'unspent' matches.

order'most_recent_first' | 'oldest_first'

Order results by their location on-chain. By default, most recent results are returned first (i.e. by descending created_at.slot_no). Within a same slot, results are ordered in function of their position in the block (i.e. transaction_index).

integer

Only fetch results that were created at and after the given slot.

OR
string

Only fetch results that were created at and after the given point. This fails if the provided point doesn't exist. It is handy to fetch a collection of results by pages while ensuring that the collection isn't being altered to due alternative chain forks being adopted. The last known fetch point can be used as starting point for the next range.

Points are defined in the usual format (same as the command-line):

          ┏━━━━━━━━━━━━━┓ ╭───╮ ┏━━━━━━━━━━━━━┓
POINT = ╾─┫ SLOT-NUMBER ┣─┤ . ├─┫ HEADER-HASH ┣─╼
          ┗━━━━━━━━━━━━━┛ ╰───╯ ┗━━━━━━━━━━━━━┛
                ┏━━━━━━━━━━━┓
HEADER-HASH = ╾─┫ 64 HEXDIG ┣───────────────────╼
                ┗━━━━━━━━━━━┛
                ┏━━━━━━━━━━┓
SLOT-NUMBER = ╾─┫ 1* DIGIT ┣────────────────────╼
                ┗━━━━━━━━━━┛

For example:

5999990.dca1e44765b9f80c8b18105e17de90d4a07e4d5a83de533e53fee32e0502d17e

Fetch only results created after (inclusive) some point.

<sup><strong>NOTE</strong></sup> <br/>

This can be combined with an upper bound (e.g. {created, spent}_before) but cannot be combined with another lower bound.

integer

Only fetch results that were spent at and after the given slot.

OR
string

Only fetch results that were spent at and after the given point. This fails if the provided point doesn't exist. It is handy to fetch a collection of results by pages while ensuring that the collection isn't being altered to due alternative chain forks being adopted. The last known fetch point can be used as starting point for the next range.

Points are defined in the usual format (same as the command-line):

          ┏━━━━━━━━━━━━━┓ ╭───╮ ┏━━━━━━━━━━━━━┓
POINT = ╾─┫ SLOT-NUMBER ┣─┤ . ├─┫ HEADER-HASH ┣─╼
          ┗━━━━━━━━━━━━━┛ ╰───╯ ┗━━━━━━━━━━━━━┛
                ┏━━━━━━━━━━━┓
HEADER-HASH = ╾─┫ 64 HEXDIG ┣───────────────────╼
                ┗━━━━━━━━━━━┛
                ┏━━━━━━━━━━┓
SLOT-NUMBER = ╾─┫ 1* DIGIT ┣────────────────────╼
                ┗━━━━━━━━━━┛

For example:

5999990.dca1e44765b9f80c8b18105e17de90d4a07e4d5a83de533e53fee32e0502d17e

Fetch only results spent after (inclusive) some point.

<sup><strong>NOTE</strong></sup> <br/>

This can be combined with an upper bound (e.g. {created, spent}_before) but cannot be combined with another lower bound.

integer

Only fetch results that were created at and before the given slot.

OR
string

Only fetch results that were created at and before the given point. This fails if the provided point doesn't exist. It is handy to fetch a collection of results by pages while ensuring that the collection isn't being altered to due alternative chain forks being adopted. The last known fetch point can be used as starting point for the next range.

Points are defined in the usual format (same as the command-line):

          ┏━━━━━━━━━━━━━┓ ╭───╮ ┏━━━━━━━━━━━━━┓
POINT = ╾─┫ SLOT-NUMBER ┣─┤ . ├─┫ HEADER-HASH ┣─╼
          ┗━━━━━━━━━━━━━┛ ╰───╯ ┗━━━━━━━━━━━━━┛
                ┏━━━━━━━━━━━┓
HEADER-HASH = ╾─┫ 64 HEXDIG ┣───────────────────╼
                ┗━━━━━━━━━━━┛
                ┏━━━━━━━━━━┓
SLOT-NUMBER = ╾─┫ 1* DIGIT ┣────────────────────╼
                ┗━━━━━━━━━━┛

For example:

5999990.dca1e44765b9f80c8b18105e17de90d4a07e4d5a83de533e53fee32e0502d17e

Fetch only results created before (inclusive) some point.

<sup><strong>NOTE</strong></sup> <br/>

This can be combined with a lower bound (e.g. {created, spent}_after) but cannot be combined with another upper bound.

integer

Only fetch results that were spent at and before the given slot.

OR
string

Only fetch results that were spent at and before the given point. This fails if the provided point doesn't exist. It is handy to fetch a collection of results by pages while ensuring that the collection isn't being altered to due alternative chain forks being adopted. The last known fetch point can be used as starting point for the next range.

Points are defined in the usual format (same as the command-line):

          ┏━━━━━━━━━━━━━┓ ╭───╮ ┏━━━━━━━━━━━━━┓
POINT = ╾─┫ SLOT-NUMBER ┣─┤ . ├─┫ HEADER-HASH ┣─╼
          ┗━━━━━━━━━━━━━┛ ╰───╯ ┗━━━━━━━━━━━━━┛
                ┏━━━━━━━━━━━┓
HEADER-HASH = ╾─┫ 64 HEXDIG ┣───────────────────╼
                ┗━━━━━━━━━━━┛
                ┏━━━━━━━━━━┓
SLOT-NUMBER = ╾─┫ 1* DIGIT ┣────────────────────╼
                ┗━━━━━━━━━━┛

For example:

5999990.dca1e44765b9f80c8b18105e17de90d4a07e4d5a83de533e53fee32e0502d17e

Fetch only results spent before (inclusive) some point.

<sup><strong>NOTE</strong></sup> <br/>

This can be combined with a lower bound (e.g. {created, spent}_after) but cannot be combined with another upper bound.

policy_idstring

Filters results to only those containing assets of a specific policy id. Useful when combined with a pattern as path-parameter.

<sup><strong>WARNING</strong></sup> <br/>

Query filters are slower than path-parameters. If you only need to match for a specific policy id, use an explicit Pattern as path-parameter instead.

asset_namestring

Filters results to only those containing assets of a specific asset id. This parameter can't be used alone and must be provided alongside a policy_id.

transaction_idstring

A blake2b-256 hash digest of a transaction body.

Example:35d8...4e09

Filters results by transaction id to retrieve items originating from that transaction only. Useful when combined with a pattern as path-parameter.

<sup><strong>WARNING</strong></sup> <br/>

Query filters are slower than path-parameters. If you only need to match for a specific transaction id, use an explicit Pattern as path-parameter instead.

output_indexinteger

Restrict results to a particular output index of a transaction. This parameter can't be used alone and must be provided alongside a transaction_id.

Response

OK