# Token price resolution Source: https://docs.settlemint.com/docs/developer-guides/api-integration/token-price-resolution Read a token price through indexed base-price feeds and FX conversion feeds. Token price resolution returns one token price in the requested fiat currency. It uses indexed feed data, not live contract reads, so API clients can display token prices and reconcile conversion paths with the feeds that produced them. ## Prerequisites [#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 [#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. ```bash 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: ```json { "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`. ## Parameters and fields [#parameters-and-fields] | Field | Type | Notes | | ------------------------------ | ------------ | ---------------------------------------------------------------------------------------------- | | `tokenAddress` | path string | Token contract address. | | `currency` | query string | Optional target ISO 4217 currency code. Defaults to `USD`. | | `price` | string | Resolved price as an 18-decimal normalized decimal string. | | `currency` | string | Currency of the returned `price`. | | `decimals` | number | Price precision. DALP returns `18`. | | `source` | string | Source of the base price. Current indexed price resolution returns `feed`. | | `sourceCurrency` | string | Currency of the base price before any FX conversion. | | `convertible` | boolean | `true` when DALP returned the requested target currency. `false` when no FX path exists. | | `targetCurrency` | string | Requested target currency. Present only when `convertible` is `false`. | | `reason` | string | Conversion failure reason. Current no-path responses use `no_fx_path`. | | `message` | string | Human-readable explanation of the missing conversion path. | | `availableCurrencies` | string\[] | Currencies reachable from the base-price currency when no path reaches the requested target. | | `updatedAt` | timestamp | Timestamp of the base-price feed used for the returned price. | | `conversionPath[]` | array | FX hops applied to the base price. Empty when no conversion was needed or when no path exists. | | `conversionPath[].from` | string | Source currency for the hop. | | `conversionPath[].to` | string | Target currency for the hop. | | `conversionPath[].rate` | string | 18-decimal normalized exchange rate for the hop. | | `conversionPath[].feedAddress` | string | Feed contract that provided the rate. | | `conversionPath[].updatedAt` | timestamp | Timestamp of the FX feed observation for the hop. | | `conversionPath[].inverse` | boolean | `true` when DALP used the inverse of the registered FX feed rate. | ## How DALP resolves the price [#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 [#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`. ```json { "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 [#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](/docs/developer-guides/feeds/create-feeds) and [submit feed updates](/docs/developer-guides/feeds/submit-updates).