Actions API

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

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.

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

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.

The token-scoped endpoint omits the five organization-only types, because they have no token to match against.

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.

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

Each item in the feed describes one action.

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

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:

multisigMetadata, present on MultisigApproval:

custodyMetadata, present on custody-pending:

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.

curl --globoff "https://your-platform.example.com/api/v2/actions?filter[status]=PENDING" \
  -H "x-api-key: YOUR_API_KEY"

{
  "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

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.

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

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

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 for the token events and transaction status surfaces. For the authentication header every request carries, see Request headers.