Request headers

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 uses the participant's direct signing wallet, a smart wallet, or the organization's default routing policy. DALP validates the participant, executor value, and account-abstraction availability before it queues a blockchain operation.

Header summary

Send participant and executor 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. Send an idempotency key on mutating requests when the client may retry after a timeout, dropped connection, or uncertain response.

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.

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.

Idempotency-Key

Idempotency-Key makes a mutating request safer to retry when the first response is uncertain. Use one unique key for one client-side instruction. Store that key next to your own instruction or job ID. Reuse it only for retries of the same request. If the payload, route, or method changes, create a new key.

DALP uses the header in two ways:

• Response-cached mutations store the key per tenant with a stable hash of the request method, route, and body. A retry with the same key and the same request can return the cached response instead of running the instruction again.
• Transaction-writing APIs use the key as part of transaction queue retry identity. Queue identity can also include the operation kind, wallet route, chain, or route-specific scope. Treat the returned transaction request, status URL, events, and indexed state as the durable record after DALP accepts the request.

For response-cached mutations, retry behavior is:

DALP keeps the response cache for 24 hours. Treat that window as retry protection, not as a permanent transaction ledger. Use transaction status and event APIs to track long-running blockchain operations after DALP accepts the request.

Validation and failure modes

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

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.

Error codes

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

Related headers

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.

Related

• API reference
• Smart wallet API overview
• Account abstraction model
• UserOperations
• Error handling