Metadata resolver API

Several DALP Platform API responses carry a metadata hash rather than the document itself. A conversion trigger event, for example, records a metadataHash that points to the off-chain terms behind it. The hash is content-addressed: it identifies the exact bytes of a payload, so the same content always produces the same hash. The metadata resolver is the read surface that turns one of those hashes into the payload it points to.

Use this reference when an API response gives you a metadata hash and you need the content behind it: the terms attached to an event, a file referenced by a token, or any other content-addressed payload the platform exposes.

Endpoint

This route returns the single-resource envelope with data and links.self. The surface is read-only: there is no list call and no mutation. Requests run in the active organization and system context of the API key session, as described in Organization and system scope.

Request

The hash is the only parameter. A hash is a bytes32 value: a 0x-prefixed, 64-character hexadecimal string. The platform validates the format before doing any resolution work, so a malformed hash fails fast with a 400 and never reaches the metadata source.

GET /api/v2/metadata/0xcccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc

Response

A resolved hash returns 200 with the payload and its content type.

{
  "data": {
    "hash": "0xcccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
    "contentType": "application/json",
    "payload": "eyJ0ZXJtcyI6IndvcmtlZCJ9"
  },
  "links": {
    "self": "/v2/metadata/0xcccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
  }
}

The payload is always Base64. Decode it before use. When contentType is a text type such as application/json, decode the Base64 to bytes and then parse the result. When the content is binary, the Base64 payload preserves the exact bytes.

const hash = "0xcccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc";
const res = await fetch(`/api/v2/metadata/${hash}`, { headers: { Authorization: "Bearer <token>" } });
const { data } = await res.json();
const bytes = Buffer.from(data.payload, "base64");
const document = data.contentType.includes("json") ? JSON.parse(bytes.toString("utf8")) : bytes;

Not found

A hash that does not resolve to content returns 404 with the DALP-0533 error. The hash format was valid, so the call did not fail validation. This status means the platform could not find content for that hash. Treat a 404 as "no content right now," not as proof that the content will never exist.

{
  "defined": true,
  "code": "METADATA_NOT_FOUND",
  "status": 404,
  "message": "Metadata not found",
  "data": {
    "id": "DALP-0533",
    "category": "client",
    "retryable": false,
    "why": "The platform could not resolve the metadata payload from the configured metadata source.",
    "fix": "Verify the metadata hash and retry after the metadata source has replicated."
  }
}

DALP-0533 is a client error and is not automatically retryable. If you expect the content to exist, confirm the hash matches the value from the source response, then retry after the metadata source has had time to replicate the content. A malformed hash returns a separate 400 validation error before any resolution is attempted. See the Platform API error reference for the shared error envelope.

Where the hash comes from

You do not construct metadata hashes yourself. The platform supplies them on the records that reference off-chain metadata, and you pass the value straight back to the resolver. For example, the conversion trigger events read surface returns a metadataHash for each trigger that carries off-chain terms; resolve that hash here to read the terms behind the event.

For the standard request headers and authentication these calls use, see Request headers.