BSV blockchainBSV blockchain

Query a lookup service

POST/lookup

Sends a lookup request to the specified lookup service. The request body must contain service (string) and query (any shape defined by the service).

By default the response is a LookupAnswer JSON object containing an array of output records. When the x-aggregation: yes header is present the response is binary (application/octet-stream): a varint-encoded outpoint list followed by aggregated BEEF.

Header Parameters

x-aggregationstring

When "yes", return a binary aggregated BEEF payload instead of the default JSON LookupAnswer.

Body application/json

servicestringrequired

Name of the lookup service to query (e.g. ls_ship).

queryanyrequired

Opaque query object whose shape is defined by the lookup service.

Response

Lookup results — JSON by default, binary when x-aggregation=yes.

type"output-list" | "freeform"

output-list — the outputs array contains UTXO records. freeform — the result field contains arbitrary data.

outputsobject[]
Show outputs properties
beefinteger[]

BEEF bytes encoding the transaction containing this output.

outputIndexinteger
contextinteger[]

Optional opaque context bytes attached by the lookup service.

resultany

Freeform result when type is freeform.

Bad request — validation error or missing required field.

statusstring
messagestring
codestring

Stable machine-readable error code (see specs/errors.md).

Unexpected internal error.

statusstring
messagestring
codestring

Stable machine-readable error code (see specs/errors.md).

Request
curl -X POST "https://{fqdn}/lookup" \
  -H "Content-Type: application/json" \
  -H "x-aggregation: <x-aggregation>" \
  -d '{
  "service": "string",
  "query": null
}'
Response
{
  "type": "output-list",
  "outputs": [
    {
      "beef": [
        0
      ],
      "outputIndex": 0,
      "context": [
        0
      ]
    }
  ],
  "result": null
}