Recipient eligibility check

The recipient eligibility endpoint returns whether one candidate address can receive a token for a given action. The endpoint reports the same registry-presence verdict the Console recipient picker uses, so an integration can block an ineligible recipient in its own form before submitting a transaction, instead of paying for an on-chain compliance revert.

Use this page for the request shape, the verdict semantics, and the boundary between this pre-check and the on-chain compliance backstop. The endpoint is a read: it never changes state and never moves a token.

When to use the pre-check

Call this endpoint when your application accepts a recipient address that a user typed or pasted, and you want to reject an ineligible recipient before signing. The Console uses it exactly this way: the mint, forced-transfer, and fee-exemption sheets validate each recipient field against this endpoint and block submit when the verdict is false.

Check one address

Send the token address in the path and the candidate recipient plus action in the query string. The action value is one of mint, transfer, or burn.

curl "https://your-platform.example.com/api/v2/tokens/0x71C7656EC7ab88b098defB751B7401B5f6d8976F/recipient-eligibility?address=0x0000000000000000000000000000000000000201&action=mint" \
  -H "X-Api-Key: sm_dalp_xxxxxxxxxxxxxxxx"

A successful response returns the verdict, the evaluated address normalized to lowercase, and the action the verdict applies to:

{
  "data": {
    "eligible": true,
    "address": "0x0000000000000000000000000000000000000201",
    "action": "mint"
  },
  "links": {
    "self": "/v2/tokens/0x71C7656EC7ab88b098defB751B7401B5f6d8976F/recipient-eligibility"
  }
}

When the address is not an eligible recipient, the same shape returns eligible: false. The endpoint returns a verdict rather than an error in this case, so treat false as a normal, expected result:

{
  "data": {
    "eligible": false,
    "address": "0x0000000000000000000000000000000000000202",
    "action": "mint"
  },
  "links": {
    "self": "/v2/tokens/0x71C7656EC7ab88b098defB751B7401B5f6d8976F/recipient-eligibility"
  }
}

Parameters and fields

What the verdict means

eligible: true means the address holds an active, registered identity in the token's own identity registry or in the organization's system identity registry. This is the recipient-picker's registry-presence definition. It is intentionally lighter than a full compliance verdict: it does not re-run every compliance module and claim that the on-chain transfer enforces.

A registration that is missing, lost, or not yet active resolves to eligible: false. A token the caller's organization scope cannot see also resolves to eligible: false rather than returning an error, so an unknown token and an ineligible address look the same to the client: a false verdict.

Because the check resolves identities against both the token registry and the system registry, an address registered at the organization level is eligible even when the per-token registry has no direct members.

The pre-check does not replace the on-chain control

The eligibility verdict is a pre-flight signal, not the final authority. The token contract still enforces compliance when the transaction executes. Use the verdict to give users fast feedback and to avoid obvious failed submissions, but design your integration so the on-chain result remains the source of truth.

A true verdict means the address is a registered identity for this token. A true verdict does not guarantee that the full transfer passes every on-chain module, amount limit, or pause and freeze control at execution time. Always handle an on-chain revert even after a true pre-check, and surface the contract's compliance error to the operator when one occurs. For the error model, see Error handling.

Related reading

• Token holders and transfers for reading current holders and transfer-related surfaces.
• Mint assets for the Console mint workflow that uses this pre-check on each recipient field.
• Compliance modules for the module-backed transfer controls the on-chain contract enforces.
• Identity verification for how a recipient becomes a registered identity in the first place.
• API reference for the generated OpenAPI contract and a typed client for this endpoint.