Transaction queue lifecycle and recovery

Every write that DALP accepts becomes a queued transaction request with its own identifier and lifecycle. A bank operating regulated assets needs to see that queue the way it sees a payment rail. List what is in flight, read where any request sits in its lifecycle, stop a request that should not proceed, and recover a request that is stuck. The transaction queue endpoints expose that surface as published REST.

Use this reference when your integration monitors queued work, builds an operator console over the queue, or implements recovery runbooks. DALP returns a transactionId whenever it accepts an asynchronous write, and every endpoint below works from that identifier. To poll a single request as a task while you wait on an asynchronous response, start with Transaction tracking. To read the mined EVM receipt for a known hash, use the blockchain transaction receipt lookup.

All endpoints are versioned under /api/v2. Reads and cancellation are scoped to the caller's wallet set; the recovery operations require organization administrator permission.

The lifecycle

A transaction request moves through an eleven-state machine from acceptance to a terminal outcome. DALP treats the queue state as the source of truth for platform finality, not a raw chain confirmation count.

Two terminal states offer operator rescue. FAILED is terminal: retries are exhausted and the request will not advance on its own. An operator can still force a FAILED request back to QUEUED through the recovery endpoint. DEAD_LETTER is a separate terminal state for requests that were stopped and need manual intervention; an operator can also rescue DEAD_LETTER back to QUEUED. Every other terminal state is final.

When a request fails, the status read carries a subStatus with finer detail, such as NONCE_CONFLICT, INSUFFICIENT_FUNDS, TIMEOUT, REPLACED, or DROPPED. Treat subStatus as diagnostic context for the current status, not as a separate lifecycle.

List the queue

GET /api/v2/transaction-requests

Return a paginated list of queue entries for monitoring and operator views. Each row carries the queue state, sender, target chain, primary hash once broadcast, and a decoded action label.

Filter with JSON:API query parameters. Combine filters to narrow a dashboard or a recovery sweep.

Results sort by createdAt ascending by default. Override with sort and page with page[limit] (default 50, maximum 200) and page[offset]. Set ownership=caller to restrict the list to the caller's own transactions even for an administrator; the default ownership=scoped lets an administrator see the organization-wide wallet set.

curl --globoff -X GET \
  "$DALP_API_URL/api/v2/transaction-requests?filter[status]=PENDING_APPROVAL&page[limit]=20" \
  --header "X-Api-Key: $DALP_API_TOKEN"

{
  "data": [
    {
      "transactionId": "01934567-89ab-7def-8123-456789abcdef",
      "kind": "token.mint",
      "status": "PENDING_APPROVAL",
      "subStatus": null,
      "fromAddress": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
      "chainId": 1,
      "transactionHash": null,
      "description": "mint(0x71C7656EC7ab88b098defB751B7401B5f6d8976F, 1000000)",
      "createdAt": "2026-03-09T10:00:00.000Z",
      "updatedAt": "2026-03-09T10:00:00.000Z"
    }
  ],
  "meta": { "total": 1 },
  "links": {
    "self": "/v2/transaction-requests?filter[status]=PENDING_APPROVAL&page[limit]=20&page[offset]=0",
    "first": "/v2/transaction-requests?filter[status]=PENDING_APPROVAL&page[limit]=20&page[offset]=0",
    "prev": null,
    "next": null,
    "last": "/v2/transaction-requests?filter[status]=PENDING_APPROVAL&page[limit]=20&page[offset]=0"
  }
}

The description field is the decoded call, such as mint(0x71C7…, 1000000). The field is null when DALP cannot decode a readable label for that row; fall back to kind.

Read a request

GET /api/v2/transaction-requests/{transactionId}

Read the full lifecycle status for one request: the operation kind, queue state, optional sub-status, primary hash, confirmed block number when available, and any recorded error. When a failed write maps to a known DALP error, the response also carries a structured contractError next to the flat errorMessage.

curl -X GET \
  "$DALP_API_URL/api/v2/transaction-requests/01934567-89ab-7def-8123-456789abcdef" \
  --header "X-Api-Key: $DALP_API_TOKEN"

{
  "data": {
    "transactionId": "01934567-89ab-7def-8123-456789abcdef",
    "kind": "token.mint",
    "status": "FAILED",
    "subStatus": "NONCE_CONFLICT",
    "transactionHash": null,
    "blockNumber": null,
    "errorMessage": "Nonce conflict on sender wallet",
    "contractError": null,
    "createdAt": "2026-03-09T10:00:00.000Z",
    "updatedAt": "2026-03-09T10:00:15.000Z"
  }
}

A status read returns the same not-found result for a missing request and for one outside the caller's wallet or organization scope. For a continuous feed from a browser context, open the server-sent events stream at GET /api/v2/transaction-requests/{transactionId}/stream. The stream requires a same-origin request or matching Origin/Host headers; programmatic API-key clients that do not send browser Sec-Fetch-Site headers should keep polling the status read instead. The stream sends an initial snapshot, then one event per transition, until a terminal state closes it.

Cancel a request

DELETE /api/v2/transaction-requests/{transactionId}

Cancel a request that should not proceed. DALP cancels a pre-broadcast request immediately. A request already broadcast to the network is cancelled with a replace-by-fee, a zero-value self-transfer that supersedes the original at the same nonce.

curl -X DELETE \
  "$DALP_API_URL/api/v2/transaction-requests/01934567-89ab-7def-8123-456789abcdef" \
  --header "X-Api-Key: $DALP_API_TOKEN"

{
  "data": {
    "status": "cancellation_pending",
    "cancelTransactionId": "0198aa11-2233-7cee-8def-445566778899"
  }
}

The status field reports cancelled for an immediate pre-broadcast cancel, cancellation_pending when a replace-by-fee transaction is racing the original on-chain, or error when the cancel could not start. A cancellation_pending result includes cancelTransactionId, which is the replacement transaction hash returned by the EVM node, not a DALP queue request identifier. Track the replacement through the blockchain transaction receipt lookup, not through the queue status read. Cancellation is scoped to the caller's wallet set: a request the caller does not own returns the same not-found result as a missing one.

Operator recovery

Three operations let an administrator recover stuck or dead-lettered work. Each requires organization administrator permission and acts only on a request whose sender wallet belongs to the administrator's organization. A request outside that scope returns not found.

Requeue a failed request

POST /api/v2/transaction-requests/{transactionId}/retries

Requeue a FAILED or DEAD_LETTER request for another attempt. DALP resets the retry counter, clears the error state, and returns the request to QUEUED. Send an optional body to override the gas price or nonce for the new attempt.

curl -X POST \
  "$DALP_API_URL/api/v2/transaction-requests/01934567-89ab-7def-8123-456789abcdef/retries" \
  --header "X-Api-Key: $DALP_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{ "gasPrice": "20000000000" }'

{
  "data": {
    "transactionId": "01934567-89ab-7def-8123-456789abcdef",
    "previousStatus": "DEAD_LETTER",
    "status": "QUEUED"
  }
}

Force a request to failed

POST /api/v2/transaction-requests/{transactionId}/failures

Force a non-terminal request to FAILED with a required reason. Use this to close out a request that cannot complete. DALP records the reason in the request history, so the operation leaves an audit trail rather than a silent state change.

curl -X POST \
  "$DALP_API_URL/api/v2/transaction-requests/01934567-89ab-7def-8123-456789abcdef/failures" \
  --header "X-Api-Key: $DALP_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{ "reason": "Manual intervention: stuck request after nonce conflict" }'

{
  "data": {
    "transactionId": "01934567-89ab-7def-8123-456789abcdef",
    "previousStatus": "BROADCASTING",
    "status": "FAILED",
    "reason": "Manual intervention: stuck request after nonce conflict"
  }
}

Reset the nonce tracker

PATCH /api/v2/transaction-requests/{transactionId}/nonce-tracker

Force-set the nonce tracker for the wallet that submitted a request. Use this to clear a stuck-nonce condition, where DALP's tracked nonce has drifted from the wallet's on-chain nonce and new transactions cannot proceed. DALP applies the nonce to the sender's tracker and returns the previous and new values.

curl -X PATCH \
  "$DALP_API_URL/api/v2/transaction-requests/01934567-89ab-7def-8123-456789abcdef/nonce-tracker" \
  --header "X-Api-Key: $DALP_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{ "nonce": 42 }'

{
  "data": {
    "previous": 40,
    "new": 42
  }
}

A previous value of null means the tracker was not yet initialized for that wallet.

Errors

A request for a row that is not in the caller's wallet set returns DALP-0383 (TRANSACTION_NOT_FOUND) with HTTP 404, indistinguishable from a genuinely missing identifier. The recovery routes require administrator permission; a caller without that permission receives DALP-0147 (OFFCHAIN_ORGANIZATION_PERMISSION_REQUIRED) or DALP-0148 (OFFCHAIN_USER_PERMISSION_REQUIRED) with HTTP 403, depending on whether the organization or the user lacks the required role. Failed writes surface their detail through errorMessage and, when the revert maps to a catalog entry, a structured contractError. See Error handling for the full model and the error code reference for individual codes.

Related

• Transaction tracking: poll a single request and read its receipt as a task.
• Mint replay, idempotency, and supply controls: the duplicate-safety model for supply-changing writes.
• Reporting and audit access: pull audit trails and operational reporting.
• API monitoring: request metrics, logs, and endpoint health.