Participant directory API reference

A participant is any person, organization, asset, claim issuer, or add-on the platform tracks in an organization, and each one owns one or more wallet addresses. A recipient picker needs two things: the list of participants a caller is allowed to select, and the right wallet address for each one. The participant directory provides both. One endpoint lists participants for a chosen address purpose, with filtering, sorting, search, and optional token eligibility. A second endpoint returns a lookup map that labels each org wallet as an externally owned account or a smart wallet, so an interface can show the correct address pill without a per-row call.

Both endpoints are read-only. They report participants and wallet classifications that already exist. They do not create participants, register identities, or move assets. For authentication and base URL setup, see Getting started.

Endpoints

The list endpoint uses the collection envelope with data, meta, and pagination links. The address-kinds endpoint uses the single-resource envelope with data and links.self. The active organization and system context bound every read, as described in Organization and system scope.

List participants

GET /api/v2/participants returns participants for a single address purpose. The purpose decides which address the platform resolves for each participant, so it is required on every call.

Each row in the result carries the resolved address for the requested purpose.

curl --globoff "https://your-platform.example.com/api/v2/participants?purpose=transfer&filter[kind]=person" \
  -H "x-api-key: YOUR_API_KEY"

{
  "data": [
    {
      "id": "par_01HXYZ",
      "kind": "person",
      "address": "0x2546BcD3c84621e976D8185a91A922aE77ECEc30",
      "displayName": "Ada Lovelace"
    }
  ],
  "meta": {
    "total": 1
  },
  "links": {
    "self": "/v2/participants?purpose=transfer&page[offset]=0&page[limit]=50",
    "first": "/v2/participants?purpose=transfer&page[offset]=0&page[limit]=50",
    "prev": null,
    "next": null,
    "last": "/v2/participants?purpose=transfer&page[offset]=0&page[limit]=50"
  }
}

Participant fields

Query controls

The list returns a single global meta.total for the current filters. It does not return per-kind facet counts, because the directory is built for address selection rather than kind breakdowns.

Filter to eligible token recipients

Add the eligibleForToken filter to narrow the list to participants who can receive a specific token. Supply the token address and the recipient action you want to check, such as a transfer or a mint.

curl --globoff "https://your-platform.example.com/api/v2/participants?purpose=transfer&eligibleForToken[tokenAddress]=0x71C7656EC7ab88b098defB751B7401B5f6d8976F&eligibleForToken[action]=transfer" \
  -H "x-api-key: YOUR_API_KEY"

When the filter hides ineligible participants, the response reports how many were removed in meta.eligibilityHiddenCount. Use reveal=true to build a show-all view that still resolves the registered recipient address for each row.

Who can list which participants

What a caller sees depends on the userSearch permission for the active system.

• A caller with the userSearch permission sees the full participant directory, including people, organizations, and claim issuers.
• A caller without that permission sees only asset and addon participants, the entries that do not expose the organization's member directory.

When a kind filter requests only kinds the caller cannot see, the endpoint returns a valid empty result rather than an error: data is empty and meta.total is 0. Treat a blank directory you did not expect as a possible permission gap, not proof that the organization has no participants.

Classify participant wallet addresses

GET /api/v2/participants/address-kinds returns a lookup map that labels each person and organization participant wallet as an externally owned account or a smart wallet. A picker reads it once and renders the correct label per address, with no extra call per row.

curl --globoff "https://your-platform.example.com/api/v2/participants/address-kinds" \
  -H "x-api-key: YOUR_API_KEY"

{
  "data": {
    "0x2546bcd3c84621e976d8185a91a922ae77ecec30": "eoa",
    "0x71c7656ec7ab88b098defb751b7401b5f6d8976f": "smart-wallet"
  },
  "links": {
    "self": "/v2/participants/address-kinds"
  }
}

The data object maps each lowercase wallet address to its kind. The kind is eoa for an externally owned account and smart-wallet for a smart wallet. The map covers the EOA and smart-wallet addresses owned by person and organization participants in the active organization.

This endpoint is gated on the same userSearch permission as the directory list. A caller without the permission receives an empty map: data is {} and links.self still points at the endpoint. An empty map for a caller you expected to be privileged points to a permission gap rather than an organization with no wallets.

When to use it

Use these endpoints when you need to:

• Populate a recipient or address picker with the participants a caller is allowed to select.
• Resolve the right address for a given purpose by choosing transfer, identity, or participant.
• Narrow a recipient list to participants eligible to receive a specific token for a transfer, mint, or burn.
• Label each address in a picker as an externally owned account or a smart wallet from a single lookup map.

To read a single participant's activity feed rather than the directory, see Participant activity. To read a participant's role assignments, see Participant role assignments.