Automation Trigger API - Onchain Suite Docs

Onchain Suite watches on-chain activity for you automatically. This API is for the cases it can’t cover: when you run your own indexer, or you need to start automations from something the platform can’t see. In those cases, you post the trigger events yourself. Each request is checked against your live automations, and every one whose trigger matches creates an entry and starts running.

When you need this. Most teams never do, EVM contract watching is automatic once an automation is published. Reach for this API only for Solana contracts, your own indexer, or lifecycle signals your systems know about. For product activity (signups, deposits, upgrades), use Custom Events instead, which resolves the contact for you and is the right tool for off-chain behavior.

Authentication

Server-to-server with a secret key. The organization is derived from the key, so no x-org-id header is needed.

Authorization: Bearer sk_live_…

Base path: https://api.onchainsuite.com/api/v1/v2/automations/runtime

Secret keys must never appear in client-side code. See API Keys.

Response

Every trigger endpoint returns the same shape:

{
  "matchedAutomations": 1,
  "entries": [
    {
      "automationId": "…",
      "entryId": "…",
      "queued": true,
      "duplicate": false
    }
  ]
}

matchedAutomations: 0 means nothing matched. Check, in order: the automation is active, it has been published, and your chain slug, contract address, and event name match the trigger spec exactly. duplicate: true means an entry already exists for this event, see Deduplication.

Endpoints

On-chain event

POST /triggers/onchain-event

string

required

Chain slug, e.g. base-mainnet.

string

required

Event name, e.g. Transfer.

string

The subject wallet. When omitted, it’s extracted from the payload based on event kind.

string

The contract the event came from.

string

Transaction hash. Strongly recommended. It backs deduplication.

string

Your own dedup key. Overrides the derived one.

object

Event data. Keys are addressable from trigger filters.

curl -X POST https://api.onchainsuite.com/api/v1/v2/automations/runtime/triggers/onchain-event \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "chain": "base-mainnet",
    "event": "Transfer",
    "contractAddress": "0xYourCollection",
    "walletAddress": "0xRecipient",
    "txHash": "0xabc...",
    "sourceEventId": "0xabc...:12",
    "payload": {
      "from": "0x0000000000000000000000000000000000000000",
      "to": "0xRecipient",
      "tokenId": "1234"
    }
  }'

This endpoint matches on the fields above: the event name, and any of contractAddress, walletAddress, and your payload keys that the automation’s trigger filters on. Always send txHash so retries are de-duplicated (see Deduplication).

For most EVM contracts you don’t need this endpoint at all. The platform watches the contract for you once the automation is published. Send events in only for Solana contracts or when you run your own indexer. See Contract-Based Flows.

Lifecycle triggers

These three fire automations whose trigger types are segment_entered, email_opened, and health_threshold. The platform does not emit them on its own, post them when the corresponding thing happens in your systems.

POST /triggers/segment-entered

Requires segmentId. Identify the contact with any of contactId, email, or walletAddress. Also accepts sourceEventId and payload.

{ "segmentId": "seg_base_minters", "walletAddress": "0xabc..." }

POST /triggers/email-opened

Accepts campaignId, deliveryId, contactId, email, walletAddress, sourceEventId, and payload. Supply campaignId or deliveryId so the open can be attributed.

{ "campaignId": "cmp_launch", "email": "user@example.com" }

POST /triggers/health-threshold

Requires a numeric score. Identify the contact with contactId, email, or walletAddress. Also accepts sourceEventId and payload.

{ "score": 25, "walletAddress": "0xabc..." }

Deduplication

Each event produces one entry per matching automation, keyed by sourceEventId. Repeating the same key returns duplicate: true and does not re-enter the automation. When you don’t supply sourceEventId, one is derived:

Trigger	Derived key
On-chain	`onchain:<chain>:<txHash>`
Segment entered	`segment:<segmentId>:<contact>`
Email opened	`email_opened:<campaignId>:<delivery>`
Health threshold	`health_threshold:<contact>:<score>`

Always send txHash on on-chain events. Without it, and without an explicit sourceEventId, the derived key falls back to random bytes, so a retried or re-delivered event creates a duplicate entry and your users get messaged twice.Send an explicit sourceEventId such as <txHash>:<logIndex> when one transaction should legitimately produce several distinct entries.

A contact can only enter a segment_entered automation once, ever, because the derived key contains no time component. For repeatable entry, send a sourceEventId that varies per occurrence.

Requirements for a match

The automation is active

Paused, draft, and archived automations are never matched.

The automation is published

An active-but-unpublished automation matches your event and creates an entry, then runs an empty graph and does nothing. This is the most common cause of “it matched but nothing happened”.

The trigger spec agrees

Any field you set on the trigger, chain, contract, event names, topic0, filters, must match. Unset fields are wildcards.

See Triggers and Conditions for the full trigger catalog and filter operators, and Contract-Based Flows for how events are normalized before matching.

Session-authenticated variant

The same trigger endpoints exist under /api/v1/automations/runtime/... using a session plus x-org-id instead of a secret key. Bodies and responses are identical. Use the v2 secret-key path for server-to-server integrations; the session path exists for dashboard-driven testing.

​Authentication

​Response

​Endpoints

​On-chain event

​Lifecycle triggers

​Deduplication

​Requirements for a match

​Session-authenticated variant

Authentication

Response

Endpoints

On-chain event

Lifecycle triggers

Deduplication

Requirements for a match

Session-authenticated variant