# Metadata resolver API

Source: https://docs.settlemint.com/docs/api-reference/reference/metadata-resolver
Resolve a content-addressed metadata hash into its payload through the DALP Platform API, with the bytes32 hash parameter, the resolved content type, the base64 payload, and the not-found error.



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 [#endpoint]

| Endpoint                      | Use it for                                                    |
| ----------------------------- | ------------------------------------------------------------- |
| `GET /api/v2/metadata/{hash}` | Resolve one content-addressed metadata hash into its payload. |

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](/docs/api-reference/reference/organization-system-scope).

## Request [#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.

```http
GET /api/v2/metadata/0xcccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc
```

## Response [#response]

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

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

| Field         | Type   | Description                                                                                                                                  |
| ------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `hash`        | string | The bytes32 hash that was resolved. It matches the hash in the request path.                                                                 |
| `contentType` | string | The media type of the resolved content, taken from the metadata source. Defaults to `application/octet-stream` when the source reports none. |
| `payload`     | string | The resolved content, Base64-encoded. Decode it according to `contentType` to recover the original bytes.                                    |

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.

```ts
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 [#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.

```json
{
  "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](/docs/api-reference/errors/platform-api-error-reference) for the shared error envelope.

## Where the hash comes from [#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](/docs/api-reference/tokens/token-conversion-triggers) 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](/docs/api-reference/reference/request-headers).