Token conversion holder state

Before a holder converts, you need to know two numbers: how much principal they hold on the token, and how much they have already converted. This endpoint reads both directly from the token's attached conversion feature, so you can show the holder an accurate, current position.

The trigger and records endpoints describe the rounds a token offers and the conversions that have completed. This endpoint is the per-holder companion: it reports one wallet's live position on the conversion feature rather than the token's published terms or its settled history.

Endpoint

Call GET /api/v2/tokens/{tokenAddress}/conversion/holder-state for the source token that carries the Conversion feature. Pass the holder wallet as a required holderAddress query parameter.

curl --globoff "$DAPI_URL/api/v2/tokens/0x1111111111111111111111111111111111111111/conversion/holder-state?holderAddress=0x2222222222222222222222222222222222222222" \
  -H "X-Api-Key: $DALP_API_TOKEN"

{
  "data": {
    "availablePrincipal": "100.50",
    "totalConverted": "25.00",
    "featureAddress": "0x3333333333333333333333333333333333333333"
  },
  "links": {
    "self": "/v2/tokens/0x1111111111111111111111111111111111111111/conversion/holder-state"
  }
}

Response fields

Both principal figures are returned as decimal strings in token units. DALP already adjusts them for the token's decimals, so you do not have to convert from smallest units yourself.

Derive how much a holder can still convert

How you compute the remaining convertible amount depends on the conversion feature's configured debt method. The endpoint returns the raw balance and historical total; you must interpret them according to how the feature reduces debt exposure.

MarkConverted method

When the feature uses MarkConverted, the source balance never decreases during conversion. Already-converted principal stays in availablePrincipal, so you must subtract the historical total to find what is still unconverted:

remaining convertible = availablePrincipal - totalConverted

In the response above, availablePrincipal is 100.50 and totalConverted is 25.00, so the holder can still convert 75.50. Sizing a request against availablePrincipal alone risks an amount the feature rejects. A holder whose totalConverted equals availablePrincipal has nothing left to convert.

Burn or Lock method

When the feature uses Burn or Lock, the converted principal is removed from the holder's balance at conversion time. availablePrincipal already reflects only the unconverted amount, so the remaining convertible amount is simply:

remaining convertible = availablePrincipal

totalConverted is still the historical cumulative total, but subtracting it from the live balance would undercount the remaining amount because the balance already excludes converted principal. For example, after a holder converts 25 of 100 with Burn, the endpoint returns availablePrincipal=75 and totalConverted=25; the holder can convert 75, not 50.

No conversion feature attached

When the token has no attached conversion feature, data is null rather than an error:

{
  "data": null,
  "links": {
    "self": "/v2/tokens/0x1111111111111111111111111111111111111111/conversion/holder-state"
  }
}

Treat a null payload as "this token does not offer conversion," not as "this holder has nothing to convert." A holder with no available principal on a token that does have the feature returns availablePrincipal of 0, not null.

Live read versus indexed read

This endpoint reads the holder's position from the conversion feature contract at query time, in a single same-block call. It reports the current on-chain state rather than an indexed snapshot, so it stays accurate as conversions settle.

Because the read goes to the contract, it depends on chain connectivity. If the conversion feature cannot be reached, DALP returns TOKEN_FEATURES_UNAVAILABLE instead of stale data. When you need the settled history of completed conversions, which is served from the index, pair this endpoint with token conversion records.

Behaviour and failure cases

• If the token address is not found in the current tenant scope, DALP returns TOKEN_INDEXER_TOKEN_NOT_FOUND.
• If the token exists but has no attached conversion feature, DALP returns data of null.
• If the conversion feature cannot be read on-chain, DALP returns TOKEN_FEATURES_UNAVAILABLE rather than guessing a value.
• The read returns the holder's current position. It does not publish a trigger, authorise a holder, or execute a conversion.

SDK and CLI

The SDK and CLI expose the same read. Use the TypeScript client for typed responses, or the CLI for quick inspection and scripting.

const holderState = await client.token.conversionHolderState({
  params: { tokenAddress: "0x1111111111111111111111111111111111111111" },
  query: { holderAddress: "0x2222222222222222222222222222222222222222" },
});

dalp tokens conversion-holder-state \
  --address 0x1111111111111111111111111111111111111111 \
  --holder 0x2222222222222222222222222222222222222222

Related

• Token conversion triggers: read the priced rounds a holder can convert against.
• Token conversion records: reconcile completed conversions and target-side issuance.
• Conversion token feature
• Token lifecycle API
• API reference