Batch Actions & Event Bus Patterns

What You'll Build

Real-world tokenization often involves operating on hundreds or thousands of objects simultaneously, airdropping rewards, expiring promotions, or updating properties in bulk. In this tutorial you'll create custom action types, execute batch actions, and learn Event Bus patterns for reliable high-throughput operations.

Step 1, Create a Custom Action Type

Action types define what operations can be performed on objects. Dual ships with built-in types (Transfer, Drop, Pickup), but you can create your own for domain-specific logic.

curl -X POST https://api-testnet.dual.network/ebus/action-types \\
  -H "Authorization: Bearer $DUAL_TOKEN" \\
  -H "Content-Type: application/json" \\
  -d '{
    "action_type": {
"name": "Redeem",
"description": "Mark a reward token as redeemed",
"template": "my-org::reward-token::v1",
"state_changes": {
  "properties.redeemed": true,
  "properties.redeemed_at": "{{timestamp}}"
}
    }
  }'

The state_changes field defines what happens to the object when this action fires. Template variables like {{timestamp}} are resolved at execution time.

Step 2, Execute a Single Action

Test your custom action on a single object first:

curl -X POST https://api-testnet.dual.network/ebus/actions \\
  -H "Authorization: Bearer $DUAL_TOKEN" \\
  -H "Content-Type: application/json" \\
  -d '{
    "action_name": "Redeem",
    "object_id": "your-object-id"
  }'

Check the object to confirm the properties changed:

curl https://api-testnet.dual.network/objects/{objectId} \\
  -H "Authorization: Bearer $DUAL_TOKEN" \\
  | jq '.properties'

Step 3, Execute Batch Actions

The batch endpoint lets you execute the same action across multiple objects in a single API call. This is far more efficient than individual requests.

curl -X POST https://api-testnet.dual.network/ebus/actions/batch \\
  -H "Authorization: Bearer $DUAL_TOKEN" \\
  -H "Content-Type: application/json" \\
  -d '{
    "actions": [
{ "action_name": "Redeem", "object_id": "object-id-1" },
{ "action_name": "Redeem", "object_id": "object-id-2" },
{ "action_name": "Redeem", "object_id": "object-id-3" }
    ]
  }'

The response returns an array of results, one per action, so you can check which succeeded and which failed.

Step 4, Query Action History

View the execution history for any object to audit what happened and when:

curl "https://api-testnet.dual.network/objects/{objectId}/activity" \\
  -H "Authorization: Bearer $DUAL_TOKEN"

What's Next?

Now that you can operate at scale, try Organization Roles & Permissions to control who can execute which actions.