# Participant eligibility

Source: https://docs.settlemint.com/docs/api-reference/compliance/participant-compliance-eligibility
Evaluate a participant against system-level compliance modules and read the verdict, reason codes, source, and per-wallet breakdown.



This endpoint evaluates whether a participant currently satisfies the compliance modules installed on your system. The platform returns one of three verdicts: `allowed`, `needs-action`, or `blocked`, together with reason codes that explain any follow-up requirement or block, and the source used to calculate the result.

## Endpoint [#endpoint]

```http
GET /api/v2/participants/{participantId}/compliance-eligibility
```

| Part            | Description                                                                                                     |
| --------------- | --------------------------------------------------------------------------------------------------------------- |
| `participantId` | Identifier of the participant whose global eligibility should be evaluated.                                     |
| `live`          | Optional query flag. Use `live=true` only for an explicit manual recheck when the indexed verdict may be stale. |

By default, the endpoint reads the indexed projection. Use that path for ordinary page renders, list refreshes, and integration polling. `live=true` bypasses the indexer and checks the installed compliance modules with live contract reads, so the request can take materially longer and should not run in bulk list views. Your API key or session must carry one of the eligibility-read roles: System manager, Identity manager, or Claim issuer.

## Request [#request]

```bash
curl --globoff "$DALP_API_URL/api/v2/participants/participant_123/compliance-eligibility" \
  --header "X-Api-Key: $DALP_API_TOKEN"
```

Add `live=true` only when you need a fresh answer after a recent compliance change. Avoid this flag in bulk list views; each call runs live contract reads and is materially slower than an indexed read:

```bash
curl --globoff "$DALP_API_URL/api/v2/participants/participant_123/compliance-eligibility?live=true" \
  --header "X-Api-Key: $DALP_API_TOKEN"
```

## Response [#response]

The result uses the single-resource API envelope. The `data` object contains the verdict, source, timestamp, and any reason codes.

```json
{
  "data": {
    "verdict": "needs-action",
    "source": "indexer",
    "checkedAt": "2026-06-06T03:00:00.000Z",
    "wallet": "0x1000000000000000000000000000000000000001",
    "reasons": [
      {
        "code": "claim-missing",
        "moduleTypeId": "identity-verification",
        "instanceAddress": "0x2000000000000000000000000000000000000002",
        "details": {
          "topic": "kyc-approved"
        }
      }
    ]
  },
  "links": {
    "self": "/v2/participants/participant_123/compliance-eligibility"
  }
}
```

When a participant has more than one wallet, the body can include `wallets` with the eligibility result for each address. The top-level verdict is the most restrictive across the wallet set: `blocked` takes precedence over `needs-action`, and `needs-action` takes precedence over `allowed`.

## Response fields [#response-fields]

| Field       | Type                                            | Description                                                                                       |
| ----------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `verdict`   | `allowed` \| `needs-action` \| `blocked`        | Overall participant eligibility verdict.                                                          |
| `source`    | `indexer` \| `live`                             | Whether the platform read the verdict from the indexer projection or from live compliance reads.  |
| `checkedAt` | timestamp                                       | Time when the verdict was calculated.                                                             |
| `wallet`    | Ethereum address or `null`                      | Wallet address assessed for this verdict. `null` means no wallet could be resolved for the check. |
| `reasons`   | array                                           | Rule-failure entries explaining `needs-action` or `blocked` verdicts.                             |
| `wallets`   | array of wallet verdict objects, when available | Per-wallet verdicts for participants with multiple wallets, such as an EOA and smart wallet pair. |

## Verdicts [#verdicts]

| Verdict        | Meaning                                                                                                | Typical operator follow-up                                                 |
| -------------- | ------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
| `allowed`      | The participant satisfies the installed system-level compliance modules for the evaluated wallet path. | Continue with the workflow that depends on eligibility.                    |
| `needs-action` | The participant is not blocked, but one or more requirements still need attention.                     | Review the reason codes, then update claims, country data, or allow lists. |
| `blocked`      | A block-list style rule matched the wallet, identity, or country.                                      | Resolve the block-list condition before relying on the participant.        |

## Reason codes [#reason-codes]

| Code                    | Verdict class  | Meaning                                                                                        |
| ----------------------- | -------------- | ---------------------------------------------------------------------------------------------- |
| `address-blocked`       | `blocked`      | The evaluated wallet is on an address block list.                                              |
| `country-blocked`       | `blocked`      | The participant identity country is on a country block list.                                   |
| `identity-blocked`      | `blocked`      | The participant identity is on an identity block list.                                         |
| `country-not-allowed`   | `needs-action` | A country allow list is configured and the participant country is missing or not allowed.      |
| `identity-not-verified` | `needs-action` | The participant identity is missing from an identity allow-list requirement.                   |
| `claim-missing`         | `needs-action` | A required trusted claim topic is absent.                                                      |
| `claim-revoked`         | `needs-action` | A required trusted claim is present but has been revoked.                                      |
| `claim-expired`         | `needs-action` | A required trusted claim is present but has expired.                                           |
| `live-timeout`          | partial result | A live compliance read timed out. DALP returns the indexed verdict with timeout reasons added. |

`details.topic` appears on claim-related reasons. `details.countryCode` is set for country-list reasons when the platform can resolve the country. `details.expiresAt` is included when a claim expiry produced the reason.

## Live recheck behaviour [#live-recheck-behaviour]

Use the indexed verdict unless you or a workflow explicitly need a fresh answer after a recent compliance change. The live path queries the installed compliance modules directly and sets `source: "live"` on the result.

If a live read times out, the platform does not fail the whole request. It returns the indexed verdict, marks the result as live-sourced, and adds `live-timeout` reasons for the modules it could not reach in time. Treat that as a partial answer and retry later before using the verdict for a sensitive decision.

## Related pages [#related-pages]

* [Compliance API route map](/docs/api-reference/compliance)
* [Compliance modules API](/docs/api-reference/compliance/compliance-modules)
* [Identity recovery API](/docs/api-reference/compliance/identity-recovery)
* [Identity and compliance](/docs/compliance-security/security/identity-compliance)