# Participant compliance eligibility API

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



Use the participant compliance eligibility API when an integration needs to check whether a participant currently satisfies the system-level compliance modules installed for the active system.

The endpoint returns one of three verdicts: `allowed`, `needs-action`, or `blocked`. It also returns reason codes that explain why the participant needs follow-up or is blocked, plus the source used to calculate the verdict.

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

The caller must have an API key or session with 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"
```

Use a live recheck only when an operator asks for a fresh answer:

```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 response uses the single-resource API envelope.

```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 response can include `wallets` with the verdict for each wallet. The top-level verdict is the most restrictive result 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 DALP evaluated the verdict from the indexer projection or from live compliance reads.      |
| `checkedAt` | timestamp                                       | Time when the verdict was evaluated.                                                               |
| `wallet`    | Ethereum address or `null`                      | Wallet address evaluated 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 appears in an address block list.                                         |
| `country-blocked`       | `blocked`      | The participant identity country appears in a country block list.                              |
| `identity-blocked`      | `blocked`      | The participant identity appears in an identity block list.                                    |
| `country-not-allowed`   | `needs-action` | A country allow list exists 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 missing.                                                     |
| `claim-revoked`         | `needs-action` | A required trusted claim exists but has been revoked.                                          |
| `claim-expired`         | `needs-action` | A required trusted claim exists but has expired.                                               |
| `live-timeout`          | partial result | A live compliance read timed out. DALP returns the indexed verdict with timeout reasons added. |

`details.topic` is present for claim-related reasons. `details.countryCode` is present for country-list reasons when DALP can resolve the country. `details.expiresAt` is present when a claim expiry produced the reason.

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

Use the indexed verdict unless a human or workflow explicitly needs a fresh check after a recent compliance change. The live path checks the installed compliance modules directly and marks the response with `source: "live"`.

If a live check times out, DALP does not fail the whole request. It returns the indexed verdict, marks the response as live-sourced, and adds `live-timeout` reasons for the modules that could not be checked in time. Treat that as a partial answer and recheck later before using the verdict for a sensitive decision.

## Related pages [#related-pages]

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