Creating Triggers

Authorize access, create webhook / schedule / chain-event triggers, fire them, and inspect run history against the Lit Triggers API.

All API calls are authenticated with a bearer token and target https://triggers.litprotocol.com. Every trigger needs a scoped Chipotle usage API key permitted to execute the action — mint one in the Dashboard or via the management API.

If you are an AI agent setting this up on a user’s behalf, a machine-readable guide lives at https://triggers.litprotocol.com/SKILL.md. It covers the browser-based authorization handshake step by step.

Authorize

Access is granted through pairing with a logged-in browser session. Generate (or reuse) a local bearer token, then send its SHA-256 hash to POST /agent/pair. The server returns a single-use authorization URL and a confirmation code.

Run this command and leave it running while you approve in the browser:

mkdir -p ~/.lit-triggers
python3 - <<'PY'
import base64, hashlib, json, pathlib, secrets, time, urllib.error, urllib.parse, urllib.request

base = 'https://triggers.litprotocol.com'
p = pathlib.Path.home() / '.lit-triggers' / 'agent-token'
if not p.exists():
    p.write_text(secrets.token_urlsafe(48))
p.chmod(0o600)
raw = p.read_text().strip()

def post(path, body, token=None):
    headers = {'content-type': 'application/json'}
    if token:
        headers['authorization'] = 'Bearer ' + token
    req = urllib.request.Request(base + path, data=json.dumps(body).encode(), headers=headers, method='POST')
    try:
        with urllib.request.urlopen(req, timeout=30) as response:
            return json.load(response)
    except urllib.error.HTTPError as error:
        raise SystemExit(f'{path}: HTTP {error.code}. Rerun this command to start a fresh pairing.')

token_hash = base64.urlsafe_b64encode(hashlib.sha256(raw.encode()).digest()).rstrip(b'=').decode()
started_at = time.monotonic()
pairing = post('/agent/pair', {'token_hash': token_hash, 'label': 'local-agent'})
print('Authorize URL:', pairing['authorize_url'], flush=True)
print('Confirmation code:', pairing['user_code'], flush=True)
print('Open the URL, sign in if needed, and only click "Authorize agent" if the code matches.', flush=True)
code = urllib.parse.parse_qs(urllib.parse.urlparse(pairing['authorize_url']).query)['code'][0]
deadline = started_at + pairing['expires_in_seconds']
while time.monotonic() < deadline:
    result = post('/agent/pair/complete', {'code': code}, raw)
    if result.get('status') == 'authorized':
        print('Agent authorized.')
        break
    if result.get('status') != 'pending':
        raise SystemExit('Unexpected pairing response: ' + json.dumps(result))
    time.sleep(3)
else:
    raise SystemExit('Pairing expired. Rerun this command to start a fresh pairing.')
PY

Open the printed URL, sign in via email if needed, and compare the code on the page with the printed confirmation code before clicking Authorize agent. The pairing expires after 10 minutes. The command polls POST /agent/pair/complete until approval is complete, proving possession of the token with a bearer header. The raw token is never included in the browser URL; it is sent to the service in the authorization header for completion and subsequent API calls.

After the command reports Agent authorized., load the saved token into your shell and verify API access. Use this same $TOKEN for the examples below:

TOKEN="$(cat ~/.lit-triggers/agent-token)"
curl -fsS -H "authorization: Bearer $TOKEN" https://triggers.litprotocol.com/api/me
# { "id": "...", "email": "[e-mail]" }

If pairing fails or expires, rerun the pairing command to get a fresh URL while keeping the saved token. A 401 from /api/me also means you need to pair again.

Create a webhook trigger

An external service POSTs JSON (or text) to a generated URL; each POST fires a run.

curl -fsS -X POST https://triggers.litprotocol.com/api/triggers \
  -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d '{
    "name": "my-webhook",
    "kind": "webhook",
    "action_code": "const main = async (params) => ({ ok: true, event: params.event });",
    "default_params": {},
    "usage_api_key": "<scoped usage key>",
    "max_runs_per_minute": 10,
    "max_queued_runs": 20,
    "config": {}
  }'
# -> { "id": "<trigger-id>", ... }

Fire it at POST /webhook/<trigger-id> (public; returns 202 with a run id):

curl -fsS -X POST https://triggers.litprotocol.com/webhook/<trigger-id> \
  -H 'content-type: application/json' -d '{"hello":"world"}'

The action receives the parsed body as params.event, the exact raw bytes as params.event_raw, and safe headers as params.headers. Verification headers (x-hub-signature-256, x-github-event, stripe-signature, x-slack-signature, …) are passed through so you can verify the sender; secret-bearing headers (authorization, cookie, x-api-key) are stripped.

Create a schedule trigger

config.cron is a 5-field cron (or 6-field with seconds). Sub-30-second schedules are rejected — the scheduler scans every 30 seconds.

curl -fsS -X POST https://triggers.litprotocol.com/api/triggers \
  -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d '{
    "name": "every-5-min",
    "kind": "schedule",
    "action_code": "const main = async (params) => ({ ranAt: params.scheduled_at });",
    "usage_api_key": "<scoped usage key>",
    "config": { "cron": "*/5 * * * *" }
  }'

Schedule runs pass params flat: { source: "schedule", scheduled_at, cron }.

Create a chain-event trigger

Fires when a log matching the contract + event signature appears on a supported chain: ethereum, base, arbitrum, bsc, polygon. The deployment must have the chain’s RPC configured.

curl -fsS -X POST https://triggers.litprotocol.com/api/triggers \
  -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d '{
    "name": "base-usdc-transfers",
    "kind": "chain_event",
    "action_code": "const main = async (p) => ({ from: p.event.decoded.arg0, amount: p.event.decoded.arg2 });",
    "usage_api_key": "<scoped usage key>",
    "config": {
      "chain": "base",
      "contract_address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "event_signature": "Transfer(address,address,uint256)"
    }
  }'

Optional config:

• start_block — integer or hex string to backfill from.
• topic_filters — up to three entries after topic0; each is a 32-byte topic, an array of topics, or null (wildcard).

Chain-event runs include ABI-decoded args (event.decoded.arg0, arg1, …) alongside the raw log, transaction hash, block number, and topics.

Inspect and manage

# list / get
curl -fsS -H "authorization: Bearer $TOKEN" https://triggers.litprotocol.com/api/triggers
curl -fsS -H "authorization: Bearer $TOKEN" https://triggers.litprotocol.com/api/triggers/<id>

# recent runs (input, status, response, error)
curl -fsS -H "authorization: Bearer $TOKEN" \
  "https://triggers.litprotocol.com/api/triggers/<id>/runs?limit=20"

# disable (stop firing) / re-enable
curl -fsS -X PATCH -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d '{"enabled": false}' https://triggers.litprotocol.com/api/triggers/<id>

# delete
curl -fsS -X DELETE -H "authorization: Bearer $TOKEN" \
  https://triggers.litprotocol.com/api/triggers/<id>

A run progresses queued → running → success | failed. Transient (5xx) failures from the Lit network are retried up to 3 times with backoff; the run’s response/error captures the action’s output or the failure (including a JS stack trace when the action throws).

API reference

Method & path	Purpose
GET /api/me	Identity check for the bearer token
POST /api/triggers	Create a trigger
GET /api/triggers	List triggers
GET /api/triggers/<id>	Get one trigger
PATCH /api/triggers/<id>	Update (e.g. enabled)
DELETE /api/triggers/<id>	Delete a trigger
GET /api/triggers/<id>/runs	Run history (?limit=&offset=)
POST /webhook/<id>	Public webhook endpoint (webhook triggers)