DALP API request headers for participant and executor selection

Select the acting participant and execution wallet for DALP API requests with X-Participant and X-Executor.

DALP API requests separate who acts from which wallet executes. X-Participant selects the acting participant for the request. X-Executor selects whether the request executes through the participant's direct signing wallet, a smart wallet, or the organization's default routing policy. DALP validates both choices before queueing a blockchain operation.

Header summary

Header	Required	Accepted values	Default when omitted
`X-Participant`	No	Canonical participant ID in `pp_<uuid>` format	The authenticated session participant
`X-Executor`	No	`eoa` or `smart-wallet`	The active organization's executor routing policy

Send these headers only when the request needs explicit identity or wallet selection. Omit them for the normal path where DALP uses the authenticated participant and the organization's configured executor routing.

Participant selection

X-Participant makes the acting participant explicit. The value must be the authenticated participant's canonical person participant ID, formatted as pp_<uuid> with lowercase UUID characters. It does not let an API key act for another participant.

curl "https://your-platform.example.com/api/v2/tokens/0x1234567890AbcdEF1234567890aBcdef12345678/holders" \
  -H "X-Api-Key: YOUR_DALP_API_KEY" \
  -H "X-Participant: pp_018f6d3e-89ab-7cde-8123-abcdefabcdef"

If X-Participant is absent, DALP acts as the participant from the authenticated session. If the header is present but malformed, DALP rejects the request as input validation. If the header names any participant other than the authenticated participant, DALP returns the same not-found shaped error whether the requested participant exists in the same tenant, exists in another tenant, or does not exist.

Executor selection

X-Executor chooses the wallet that executes a blockchain operation for the selected participant.

Header value	Effect	When to use it
Omitted	Uses the active organization's default executor routing. If account-abstraction routing is enabled, the executor resolves to the participant's smart wallet. If it is not enabled, the executor resolves to the participant's signing wallet.	Most integrations
`eoa`	Forces raw execution through a personal participant's externally owned account.	Use only when the workflow must execute from the direct signer account. DALP rejects this value for non-person participants.
`smart-wallet`	Forces smart-wallet execution, regardless of the organization's default account-abstraction routing policy.	Use when the workflow must execute through a smart wallet. For person participants, DALP can provision the participant smart wallet during the request.

The executor selected for the request becomes the effective wallet address that the smart contract sees as the caller. Route handlers use that resolved executor for role checks and user operation submission.

Use both headers together

The participant header answers who acts. The executor header answers which wallet acts for that participant. A request can set both when the caller wants the identity and executor choice to be explicit.

curl -X POST "https://your-platform.example.com/api/v2/tokens/0x1234567890AbcdEF1234567890aBcdef12345678/mints" \
  -H "X-Api-Key: YOUR_DALP_API_KEY" \
  -H "Idempotency-Key: mint-2026-05-17-001" \
  -H "X-Participant: pp_018f6d3e-89ab-7cde-8123-abcdefabcdef" \
  -H "X-Executor: smart-wallet" \
  -H "Content-Type: application/json" \
  -d '{
    "recipients": ["0x1111111111111111111111111111111111111111"],
    "amounts": ["1000"]
  }'

This request says: act as participant pp_018f6d3e-89ab-7cde-8123-abcdefabcdef, execute through that participant's smart wallet, and submit the mint operation once for the supplied idempotency key.

Validation and failure modes

DALP validates participant and executor selection before queueing a blockchain operation.

Condition	Result	Caller action
`X-Participant` is malformed	The request fails input validation.	Use a canonical `pp_<uuid>` participant ID.
`X-Participant` names a participant other than the authenticated participant	The request returns a not-found shaped participant error.	Remove the header or send the authenticated participant ID.
`X-Executor` is not `eoa` or `smart-wallet`	The request fails input validation.	Omit the header or send one of the supported values.
`X-Executor: eoa` is sent for a non-person participant	The request fails because EOA execution is not supported for that participant type.	Omit the header or use `smart-wallet` when the participant has an available smart wallet.
`X-Executor: smart-wallet` cannot resolve a usable smart wallet	The request fails before submission.	Retry after wallet availability is restored, or omit the override.

Route applicability

DALP exposes X-Participant and X-Executor in the OpenAPI specification on routes that can use participant or executor selection. Check /api/v2/spec.json for the operation you call before adding the headers.

Route type	Header behavior
Transaction routes that queue blockchain operations	DALP validates the selected participant and executor before queueing the operation.
Token indexer reads that use participant context	DALP can use the selected participant to scope the read.
Smart wallet approval routes	DALP can use explicit executor selection when creating or signing approvals.
Routes that do not list these headers in OpenAPI	Treat the headers as not applicable. Omit them instead of relying on them.

Error codes

Error code	Public error	When it happens
`DALP-0524`	`X_PARTICIPANT_FORBIDDEN`	`X-Participant` is well formed but does not match the authenticated participant.
`DALP-0530`	`X_EXECUTOR_UNSUPPORTED_FOR_PARTICIPANT_TYPE`	`X-Executor: eoa` is used for a participant type that cannot execute through an EOA.
`DALP-0531`	`X_EXECUTOR_NO_SMART_WALLET`	`X-Executor: smart-wallet` is used when no smart wallet is available for the selected participant.

Malformed participant IDs and unsupported executor values return input validation errors before DALP queues the operation.

Use Idempotency-Key with mutating requests so retries do not submit duplicate operations. Use Prefer when a transaction route supports response timing preferences. X-Transaction-Speed is a parsed request header on routes that expose it; leave it unset unless route documentation or your integration contract tells you to send an explicit speed preference. X-User-Id and X-Organization-Id are internal response headers used by the API layer and are not request headers for integrations.

Request headers