Request headers

DALP API requests separate who acts, which wallet executes, and which network runs the operation. 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 organisation's default routing policy. X-Chain-Id targets a specific network. Before queueing a blockchain operation, DALP validates the participant, executor value, account-abstraction availability, and requested network.

Header summary

All six headers are optional. The table below shows accepted values and what the Platform API uses when each header is omitted.

Omit the identity, executor, and network headers on the normal path. Use them only when the request needs explicit identity, wallet, or network selection. Include an idempotency key on mutating requests when the client may retry after a timeout, dropped connection, or uncertain response.

Use Prefer to control whether a transaction request returns on acceptance or waits for the operation to settle.

Participant selection

X-Participant makes the acting participant explicit. The value must be a canonical participant ID, formatted with a kind prefix and a lowercase identifier, such as pp_<uuid> for a person participant. A user may name their own person participant or any participant they are entitled to assume, such as an organization they administer. See Participant assumption for who a user may act as and how to list the assumable set.

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"

When X-Participant is absent, DALP acts as the participant from the authenticated session. A malformed header causes DALP to reject the request as input validation. When the header names a participant the user may not assume, DALP returns the same not-found shaped error whether the requested participant is one the user cannot assume, exists in another organization, or does not exist. See Participant assumption for the assumption rules and the assumable-participants endpoint.

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.

Network selection

X-Chain-Id names the network a request targets. Send the numeric chain ID of the network you want. When you omit the header, DALP uses the organisation's default network, so single-network integrations never need to set it.

curl "https://your-platform.example.com/api/v2/tokens" \
  -H "X-Api-Key: YOUR_DALP_API_KEY" \
  -H "X-Chain-Id: 31337"

DALP resolves the header strictly:

• The value must be a positive decimal integer with no leading zeros, no greater than 2147483647. Anything else fails input validation.
• Naming the organisation's default network behaves exactly like omitting the header, so onboarding organisations that have no other network configured keep working without change.
• Naming any other network requires multi-network support on the active organisation and an active system on that network. DALP accepts the request only when both hold.

A request that names a network the organisation cannot target fails before DALP queues any blockchain operation. The error tells you whether the organisation has no access to that network, or has the network registered but not yet ready, so a client can fall back to the default network or wait for a deployment to finish. See Error codes for the exact codes.

DALP validates the requested network on every authenticated request. Set a non-default X-Chain-Id only on operations whose documentation states they support a non-default network; other operations run on the organisation's default network regardless of the header. When in doubt, omit the header and target the default network.

Transaction speed

X-Transaction-Speed declares a gas-price strategy preference for a blockchain operation. The Platform API accepts this header on mutating transaction routes and publishes it in the OpenAPI specification. It accepts three values:

The header is case-insensitive and optional. DALP normalises the value and falls back to normal when the header is absent, empty, or set to anything outside the three accepted values, so a request never fails because of this header alone. This differs from X-Chain-Id, which rejects malformed values.

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-Transaction-Speed: fast" \
  -H "Content-Type: application/json" \
  -d '{
    "recipients": ["0x1111111111111111111111111111111111111111"],
    "amounts": ["1000"]
  }'

Send X-Transaction-Speed only on mutating transaction routes that list it in the OpenAPI specification. The header is accepted and parsed, but the gas-price strategy is not yet applied to the transaction. Omit it to use the normal strategy. Check /api/v2/spec.json for the operation you call before adding the header.

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.

Send the standard Idempotency-Key spelling in new integrations. DALP accepts a non-empty string value and trims surrounding whitespace. If the client omits the header, DALP can create a server-side key for that request, but the client cannot reuse that generated value after a lost response. Production integrations should send their own key whenever a retry may be needed.

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 once the Platform API queues the request.

A reused key on a different request returns DALP-0514, and a key whose original request is still running returns DALP-0515. Both are listed in Error codes below.

Prefer (response timing)

Prefer controls whether a transaction request returns as soon as DALP accepts it or waits for the blockchain operation to settle. DALP follows the wait preference from RFC 7240. Transaction routes are asynchronous by default: DALP accepts the request, returns 202 Accepted with a status URL, and runs the operation in the background. Poll the status URL until the transaction reaches a terminal state.

Send Prefer: wait=N to wait synchronously instead. DALP holds the response for up to N seconds while it attaches to the operation. The wait window clamps to between 5 and 99 seconds, with a 5-second floor and a 99-second ceiling.

• If the operation reaches a terminal state within the wait budget, DALP returns 200 OK with the settled result.
• If the time limit elapses first, DALP degrades to the same 202 Accepted status-URL response. Poll the status URL from there.
• To opt out of waiting entirely and get the 202 Accepted handle immediately, send Prefer: respond-async.

A synchronous wait never changes the outcome of the operation. It only changes whether DALP returns the result inline or hands back a status URL to poll. DALP echoes the directives it honored in the Preference-Applied response header.

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 "Prefer: wait=30" \
  -H "Content-Type: application/json" \
  -d '{
    "recipients": ["0x1111111111111111111111111111111111111111"],
    "amounts": ["1000"]
  }'

This request waits up to 30 seconds for the mint to settle. If it settles in time, the response carries the terminal result. If not, the response is the standard 202 Accepted handle to poll.

SDK default

The DALP SDK sends Prefer: wait=99 on mutating calls unless you set your own Prefer header. SDK mutations therefore complete synchronously in most cases and return the settled result directly, rather than a handle to poll.

To opt back into the asynchronous handle, set Prefer: respond-async when you create the client or when you make the call.

When to use it

Choose the Prefer value that matches your flow.

Use a synchronous wait for short interactive flows. Use the asynchronous path for long-running operations, batch jobs, or flows that already poll transaction status.

Pair Prefer with Idempotency-Key so a retry after a degraded 202 attaches to the original instruction instead of submitting a new one.

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.

DALP-0515 is retryable and carries a retryAfterSeconds hint in its error data. Wait for the in-flight request to finish, then retry the same request with the same key. DALP-0514 is not retryable: keep the original key for the original request and create a new key for any changed instruction. For the full entries, see DALP-0514 and DALP-0515.

Related headers

Use Prefer when a transaction route supports response-timing preferences. Use X-Transaction-Speed to set a gas-price strategy on mutating transaction routes that list it in OpenAPI. X-User-Id and X-Organization-Id are internal response headers, not request headers for integrations.

Related

• API reference
• XvP settlement flows
• Smart wallet API overview
• Advanced accounts concept
• UserOperations
• Error handling