# Actions API Source: https://docs.settlemint.com/docs/api-reference/reference/actions List the pending and historical operational actions across an organization or one token through the DALP Platform API, with status, type, and per-action metadata for review and execution. An action is a time-bound operational task an authorized user can act on. Examples include a bond reaching maturity, a yield claim coming due, an allowance or settlement approval, a KYC update step, a multisig approval, and a transaction waiting on a custody provider. The actions feed gives an operator one place to see what is pending, what is upcoming, and what already executed, instead of checking each contract and queue separately. The feed is read-only and user-scoped. It reports actions and their status without approving, executing, or changing anything. Each caller sees only the actions they are eligible to act on, so two operators in the same organization can receive different feeds from the same request. ## Endpoints [#endpoints] | Endpoint | Use it for | | ------------------------------------------- | ---------------------------------------------------------------------------------- | | `GET /api/v2/actions` | List every action across the active organization that the caller can act on. | | `GET /api/v2/tokens/{tokenAddress}/actions` | List the actions attached to one token, including its features and yield schedule. | Both endpoints use the collection envelope with `data`, `meta`, and pagination `links`. The active organization and system context bound every read, as described in [Organization and system scope](/docs/api-reference/reference/organization-system-scope). The two endpoints differ in scope. The organization feed includes off-chain action types that have no token to attach to, such as KYC updates, multisig approvals, and pending custody approvals. The token-scoped feed covers only on-chain actions for that token. It resolves the token together with its attached feature contracts and its yield schedule, so an allowance approval whose target is a feature contract still appears alongside the bond it belongs to. ## Path parameters [#path-parameters] | Parameter | Type | Description | | -------------- | ------ | --------------------------------------------------------------- | | `tokenAddress` | string | The token whose actions to list, for the token-scoped endpoint. | ## Action types [#action-types] `actionType` is the stable identifier the platform uses for filtering and execution routing. It stays the same even when the display `name` changes. | Action type | Surfaces on | Meaning | | -------------------------- | ---------------------- | ------------------------------------------------------------------- | | `MatureBond` | organization and token | A bond has reached its maturity date and can be matured. | | `RedeemBond` | organization and token | A matured bond can be redeemed by a holder. | | `ClaimYield` | organization and token | A yield distribution is available to claim. | | `ApproveMaturityAllowance` | organization and token | An allowance the maturity flow needs is pending approval. | | `ApproveYieldAllowance` | organization and token | An allowance the yield flow needs is pending approval. | | `ApproveXvPSettlement` | organization only | A delivery-versus-payment settlement is waiting for an approval. | | `ExecuteXvPSettlement` | organization only | An approved delivery-versus-payment settlement is ready to execute. | | `UpdateKYCData` | organization only | A participant has been asked to update their KYC data. | | `MultisigApproval` | organization only | A multisig operation is waiting for the caller's signature. | | `custody-pending` | organization only | A transaction is waiting on the organization's custody provider. | The token-scoped endpoint omits the five organization-only types, because they have no token to match against. ## Status lifecycle [#status-lifecycle] `status` reports where an action sits in time, computed against the action's activation and expiry timestamps at the moment of the request. | Status | Meaning | | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `UPCOMING` | The action is scheduled but its activation time has not arrived yet. | | `PENDING` | The action is active and waiting to be executed. | | `EXECUTED` | The action has been carried out. `executedAt` and `executedBy` are set when the execution is recorded on-chain; they may be `null` for off-chain completions such as fulfilled KYC updates or multisig approvals that map a raw executed status without signer attribution. | | `EXPIRED` | The action passed its expiry without being executed. | Both `status` and `actionType` are faceted, so `meta.facets` reports how many actions carry each value in the current result set. Use the facets to build a status filter or a type filter without a second request. ## Action fields [#action-fields] Each item in the feed describes one action. | Field | Type | Description | | ------------------ | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | Unique identifier for the action. | | `actionType` | string | The canonical action type, used for filtering and execution routing. | | `name` | string | Human-readable display name of the action. | | `target` | string or `null` | The contract address the action acts on. `null` for off-chain actions. | | `tokenAddress` | string or `null` | The underlying token an action targets when it differs from `target`. `null` for off-chain actions. For XvP settlement actions this is the settlement address, not an underlying token. | | `status` | string | Current status: `UPCOMING`, `PENDING`, `EXECUTED`, or `EXPIRED`. | | `activeAt` | string | Timestamp when the action becomes active. | | `expiresAt` | string or `null` | Timestamp when the action expires. `null` when the action does not expire. | | `executedAt` | string or `null` | Timestamp when the action was executed. `null` until it is. | | `executedBy` | string or `null` | Address that executed the action. `null` until it is executed. | | `source` | string | `on-chain` for indexed blockchain actions, `off-chain` for actions held off-chain such as KYC updates. | | `kycMetadata` | object or `null` | Present for KYC update actions. Carries the request reason, the fields to update, and the request id. | | `multisigMetadata` | object or `null` | Present for multisig approvals. Carries the operation hash, wallet address, threshold, and current weight. | | `custodyMetadata` | object or `null` | Present for pending custody approvals. Carries the provider, whether it can be resolved in-app, and the approval id. | ### Reading `target` against `tokenAddress` [#reading-target-against-tokenaddress] For most on-chain actions `target` is the contract the action acts on, and `tokenAddress` names the token behind it. They differ when the action sits on a feature of the token rather than the token itself. A yield claim targets the yield schedule, but `tokenAddress` still names the bond. A reader can therefore group every action for one bond without knowing each feature address. Off-chain actions usually have both fields `null`, with the metadata block carrying the context instead. The exception is `MultisigApproval`: its `source` is `off-chain` yet `target` is set to the smart wallet address the approval applies to, so an integrator filtering by `target` still sees multisig rows. ### Per-type metadata blocks [#per-type-metadata-blocks] Off-chain action types carry a metadata block with the context an operator needs to act. Only the block that matches the action type is populated; the others are absent or `null`. `kycMetadata`, present on `UpdateKYCData`: | Field | Type | Description | | ----------------- | ------ | ------------------------------------------------- | | `reason` | string | Why the update was requested. | | `requiredFields` | array | The participant data fields that need updating. | | `sourceVersionId` | string | The version to clone data from for the new draft. | | `requestId` | string | Identifier of the KYC update request. | `multisigMetadata`, present on `MultisigApproval`: | Field | Type | Description | | --------------- | ---------------- | -------------------------------------------------------------------------- | | `userOpHash` | string | The operation hash to pass to the sign-approval call. | | `walletAddress` | string | The smart wallet the approval applies to. | | `threshold` | string | Required cumulative signer weight, as a decimal string. | | `currentWeight` | string | Signer weight gathered so far, as a decimal string. | | `description` | string or `null` | Human-readable summary of the pending operation. | | `operationKind` | string or `null` | The operation kind awaiting signatures, such as `smart-wallet.add-signer`. | `custodyMetadata`, present on `custody-pending`: | Field | Type | Description | | --------------- | ---------------- | ----------------------------------------------------------------------------------------- | | `provider` | string | The custody provider backing the approval. | | `executable` | boolean | Whether the approval can be resolved in-app, or only observed while resolved out of band. | | `approvalId` | string or `null` | The provider approval id for the resolve-approval call. `null` for out-of-band providers. | | `transactionId` | string or `null` | The transaction the approval blocks, when known. | | `operationKind` | string or `null` | Human-readable operation kind awaiting approval. | ## List actions across an organization [#list-actions-across-an-organization] `GET /api/v2/actions` returns every action across the active organization that the authenticated caller is eligible to act on, newest by activation time first. The feed supports pagination, sorting, and filtering by `status`, `actionType`, `target`, `tokenAddress`, and `name`, plus global search with `filter[q]`. The default sort is newest first by `activeAt`. ```bash curl --globoff "https://your-platform.example.com/api/v2/actions?filter[status]=PENDING" \ -H "x-api-key: YOUR_API_KEY" ``` ```json { "data": [ { "id": "action-001", "actionType": "ApproveXvPSettlement", "name": "Settlement approval for Series A", "target": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F", "tokenAddress": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F", "status": "PENDING", "activeAt": "2024-01-15T10:30:00.000Z", "expiresAt": "2024-02-15T10:30:00.000Z", "executedAt": null, "executedBy": null, "source": "on-chain" } ], "meta": { "total": 1, "facets": { "status": [{ "value": "PENDING", "count": 1 }], "actionType": [{ "value": "ApproveXvPSettlement", "count": 1 }] } }, "links": { "self": "/v2/actions?page[offset]=0&page[limit]=50", "first": "/v2/actions?page[offset]=0&page[limit]=50", "prev": null, "next": null, "last": "/v2/actions?page[offset]=0&page[limit]=50" } } ``` The feed returns 50 actions per page by default, up to 200. Use `page[offset]` and `page[limit]` to page through longer histories. ## List actions for one token [#list-actions-for-one-token] `GET /api/v2/tokens/{tokenAddress}/actions` returns the on-chain actions attached to one token. It resolves the token together with its attached feature contracts and its yield schedule, so allowance and yield actions whose `target` is a feature or schedule address still appear for the token they belong to. ```bash curl --globoff "https://your-platform.example.com/api/v2/tokens/0xTOKEN_ADDRESS/actions?filter[status]=PENDING" \ -H "x-api-key: YOUR_API_KEY" ``` This endpoint accepts the same query parameters as the organization feed, except that the off-chain action types never appear in the result. ## Empty results and scope [#empty-results-and-scope] The feed is always scoped to the caller's wallet set, so it lists only the actions that caller is eligible to act on. A caller with no resolvable wallet for the active organization, or a session that is still partly onboarded, receives a valid response with an empty `data` array and a `meta.total` of `0` rather than an error. Treat a quiet feed where you expected open work as a possible wallet or eligibility gap, not proof that nothing is pending. ## When to use it [#when-to-use-it] Use these endpoints when you need to: * Show an operator every pending and upcoming action they can act on across the organization, in one feed. * List the operational actions attached to a single token, including its features and yield schedule. * Confirm whether a maturity, redemption, yield claim, allowance approval, XvP settlement, KYC update, multisig approval, or custody approval is pending, upcoming, executed, or expired. * Read the per-action metadata a multisig or custody approval needs before signing or resolving it. To confirm the on-chain result after an action executes, see [Reporting and audit access](/docs/api-reference/observability/reporting-audit-access) for the token events and transaction status surfaces. For the authentication header every request carries, see [Request headers](/docs/api-reference/reference/request-headers).