# Recipient eligibility check

Source: https://docs.settlemint.com/docs/api-reference/tokens/recipient-eligibility
Check whether one address can receive a token for a mint, transfer, or burn before you submit the on-chain transaction.



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

| Decision                                                | Use the recipient eligibility endpoint for                              | Check outside the endpoint                                                         |
| ------------------------------------------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| Can I show this address as an eligible recipient?       | A `true`/`false` verdict for one address and one action.                | Whether the wider transfer also satisfies amount, freeze, or pause controls.       |
| Should my form block submit before signing?             | The pre-check verdict, refreshed for the action the user is performing. | The authoritative on-chain result, which the contract still enforces at execution. |
| Is this address registered for this token's compliance? | Whether the address holds an active, registered identity for the token. | Whether every on-chain compliance module and claim passes for the full transfer.   |

## Check one address [#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`.

```bash
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:

```json
{
  "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:

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

## Parameters and fields [#parameters-and-fields]

| Field          | Type         | Notes                                                                                           |
| -------------- | ------------ | ----------------------------------------------------------------------------------------------- |
| `tokenAddress` | path string  | The token contract address to check eligibility against.                                        |
| `address`      | query string | The candidate recipient address whose eligibility is being checked.                             |
| `action`       | query string | The recipient-targeting action: `mint`, `transfer`, or `burn`.                                  |
| `eligible`     | boolean      | `true` when the address holds an active, registered identity in the token's or system registry. |
| `address`      | string       | The evaluated address, echoed back normalized to lowercase.                                     |
| `action`       | string       | The action the verdict applies to, echoed back from the request.                                |

## What the verdict means [#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-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](/docs/api-reference/errors/error-handling).

## Related reading [#related-reading]

* [Token holders and transfers](/docs/api-reference/tokens/token-holders-transfers) for reading current holders and transfer-related surfaces.
* [Mint assets](/docs/operators/asset-servicing/mint-assets) for the Console mint workflow that uses this pre-check on each recipient field.
* [Compliance modules](/docs/api-reference/compliance/compliance-modules) for the module-backed transfer controls the on-chain contract enforces.
* [Identity verification](/docs/compliance-security/compliance/identity-verification) for how a recipient becomes a registered identity in the first place.
* [API reference](/docs/api-reference/reference/openapi) for the generated OpenAPI contract and a typed client for this endpoint.