Token price resolution

Token price resolution returns one indexed token price in the requested fiat currency. DALP reads the indexed PriceResolver configuration, base-price feeds, and global FX feeds. API clients use the response to show prices, explain the conversion path, and detect feed setup gaps before a valuation or asset workflow depends on stale data.

Use this page for the response shape, conversion rules, and setup checks for token pricing. To submit a new price observation, use the related write endpoint described below.

Prerequisites

Before you call the endpoint, the token must be indexed in your organization scope. The token also needs an active base-price feed. If the token uses a PriceResolver, that base-price feed must be registered in the PriceResolver feeds directory.

For converted prices, the feeds directory also needs active global FX feeds that connect the base price currency to the requested target currency.

Read a token price

Call the token price endpoint with the token address in the path. The optional currency query parameter selects the target ISO 4217 fiat currency. If you omit it, DALP resolves the price in USD.

curl "https://your-platform.example.com/api/v2/tokens/0x71C7656EC7ab88b098defB751B7401B5f6d8976F/price?currency=USD" \
  -H "X-Api-Key: sm_dalp_xxxxxxxxxxxxxxxx"

A successful converted response includes the resolved price and the FX hops DALP used to reach the target currency:

{
  "data": {
    "tokenAddress": "0x71c7656ec7ab88b098defb751b7401b5f6d8976f",
    "price": "27230000000000000000",
    "currency": "USD",
    "decimals": 18,
    "source": "feed",
    "sourceCurrency": "AED",
    "convertible": true,
    "updatedAt": "2026-03-22T10:30:00.000Z",
    "conversionPath": [
      {
        "from": "AED",
        "to": "USD",
        "rate": "272300000000000000",
        "feedAddress": "0xabcdef1234567890abcdef1234567890abcdef12",
        "updatedAt": "2026-03-22T10:29:00.000Z",
        "inverse": false
      }
    ]
  },
  "links": {
    "self": "/v2/tokens/0x71C7656EC7ab88b098defB751B7401B5f6d8976F/price"
  }
}

If the base-price currency already matches the requested currency, DALP returns convertible: true and an empty conversionPath.

Read versus update

DALP exposes the same token price path for two different API jobs:

The read endpoint always returns an 18-decimal normalized price string. The write endpoint accepts the submitted price as a positive decimal string. The token price feed workflow then records the value through DALP's feed system.

Write response shapes

POST /api/v2/tokens/{tokenAddress}/price can complete during the request or be accepted for asynchronous processing.

When the mutation completes during the request, DALP returns the feed update details with transaction metadata:

{
  "data": {
    "feedAddress": "0xabcdef1234567890abcdef1234567890abcdef12",
    "txHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "price": "100.50",
    "currencyCode": "USD"
  },
  "meta": {
    "txHashes": ["0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"]
  },
  "links": {
    "self": "/v2/tokens/0x71C7656EC7ab88b098defB751B7401B5f6d8976F/price"
  }
}

When the mutation is queued, DALP returns HTTP 202 with the asynchronous status handle instead of data fields:

{
  "transactionId": "01965a1b-7d8c-7d9f-9f3a-5f4c2d1e0b9a",
  "status": "QUEUED",
  "statusUrl": "/api/v2/transaction-requests/01965a1b-7d8c-7d9f-9f3a-5f4c2d1e0b9a"
}

If the response has statusUrl, store the transactionId and poll that URL until the transaction reaches a terminal status before treating the price update as complete. Do not require data.feedAddress or data.txHash on an HTTP 202 response.

Parameters and fields

How DALP resolves the price

DALP first finds the indexed token in the caller's organization and system scope. It then looks for an active PriceResolver configuration for the token's system. If the token has a PriceResolver, DALP reads base-price and FX feeds from the configured feeds directory. If no PriceResolver configuration is indexed, DALP falls back to active indexed feeds for the token.

The base price comes from an active token-specific feed whose description parses as a currency pair and is not an FX pair. DALP normalizes the feed answer to 18 decimals, uses the pair quote as sourceCurrency, and returns source: "feed".

When a PriceResolver is active, DALP enforces the resolver's maximum staleness policy on the base-price feed. If the latest base-price observation is older than the configured limit, the request fails instead of returning a stale price. If the resolver has no indexed staleness configuration, DALP uses 86,400 seconds.

For conversion, DALP builds an FX graph from active global FX feeds in the same feeds directory. Each feed adds a direct edge and an inverse edge. DALP searches for the shortest path from sourceCurrency to the requested currency, with a maximum of three FX hops, then applies each 18-decimal rate in order.

When convertible is false

If DALP finds a valid base price but cannot find an FX path to the requested currency, the endpoint still returns the base price. In that case, currency remains the base-price currency, targetCurrency records the requested currency, convertible is false, and reason is no_fx_path.

{
  "data": {
    "tokenAddress": "0x71c7656ec7ab88b098defb751b7401b5f6d8976f",
    "price": "1000000000000000000",
    "currency": "AED",
    "decimals": 18,
    "source": "feed",
    "sourceCurrency": "AED",
    "convertible": false,
    "targetCurrency": "USD",
    "reason": "no_fx_path",
    "message": "No conversion path from AED to USD exists in the configured PriceResolver feeds directory.",
    "availableCurrencies": ["EUR"],
    "updatedAt": "2026-03-22T10:30:00.000Z",
    "conversionPath": []
  },
  "links": {
    "self": "/v2/tokens/0x71C7656EC7ab88b098defB751B7401B5f6d8976F/price"
  }
}

Treat convertible: false as a setup signal, not as a missing token price. The base price exists, but the configured feed graph does not connect it to the requested currency within the supported hop limit.

Feed setup requirements

To make a token price convertible, configure these feeds in the same feeds directory used by the token's PriceResolver:

1. An active token-specific base-price feed for the token address.
2. A feed description that parses as the base-price currency pair.
3. A latest answer and observation timestamp for the base-price feed.
4. Active global FX feeds that connect the base-price currency to each display currency your integration requests.
5. Fresh observations for all feeds used by an active PriceResolver policy.

For feed creation and update workflows, see create feeds and submit feed updates. For the wider market-data model, see market data infrastructure and data feeds overview.

Troubleshoot price setup

Current API price resolution is feed-only. It does not guess token prices from identity claims when a base-price feed is missing.

Use this checklist when the endpoint cannot return the requested price:

1. Confirm the token address in the request is the asset that needs a price.
2. Confirm the token is indexed in the caller's organization scope and system scope.
3. Check that the indexed PriceResolver configuration points to the expected feeds directory.
4. Register or reactivate a token-specific base-price feed for the token and resolver topic.
5. Publish the latest answer with the expected decimals and observation timestamp.
6. For converted prices, register active global FX feeds in the same feeds directory until the base currency connects to the requested display currency.
7. Retry after the base-price and FX updates are indexed.

Holder eligibility and compliance are separate from the price source. Price resolution does not replace KYC, sanctions, or transfer-control checks.

For feed setup, see create feeds and submit feed updates. For identity claim setup outside the price endpoint, see configure trusted issuers and choose a KYC issuance path.