> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shuriken.trade/llms.txt
> Use this file to discover all available pages before exploring further.

# Triggers

> Three ways your Labs agent can fire. Schedule it, react to your own trades, or invoke it from an API.

Triggers decide when an agent runs. You can attach more than one. Each fires independently and produces its own session you can review later from the run history.

## Three trigger types

<CardGroup cols={3}>
  <Card title="On a schedule" icon="clock" href="#on-a-schedule">
    Fire on a recurring cadence. Cron, but with a friendly UI.
  </Card>

  <Card title="When I make a trade" icon="arrow-right-arrow-left" href="#when-i-make-a-trade">
    Fire after your own buys, sells, or both. With cooldown.
  </Card>

  <Card title="Allow API calls" icon="code" href="#allow-api-calls">
    Invoke from a webhook, an MCP client, or any HTTP request.
  </Card>
</CardGroup>

## On a schedule

Schedules run the agent on a recurring cadence. Useful for morning briefings, weekly recaps, and any hands-off task you want to wake up to.

**Frequencies:** minutely, hourly, daily, weekly, monthly. Each one shows the relevant pickers: weekday for weekly, day-of-month for monthly, hour and minute for daily and below.

**Timezone:** required. Defaults to your browser's timezone so a schedule respects your local time, not UTC. You can pick any timezone from the dropdown.

**Example: morning briefing.**

```
What you set: Daily, 09:00, America/New_York, Mon–Fri.
When it fires: Every weekday at 09:00 New York time. The session lands in your run history.
```

**Example: weekly recap.**

```
What you set: Weekly, Sunday, 22:00 UTC.
When it fires: Every Sunday at 22:00 UTC. One session per week.
```

<Note>
  The agent runs under your scoped agent key. Per-trade and daily limits still apply, so a runaway schedule can't exceed them. If you hit your daily cap mid-schedule, the next fire skips trades and just reports.
</Note>

## When I make a trade

Trade triggers fire right after *you* execute a trade through Shuriken (Terminal, Telegram, NLP, or the API). They do not fire off other people's wallets or alpha calls.

**Action filter:** buy, sell, or any. You can attach two trade triggers at once with different actions (one for buy, one for sell), but only one configured as `any`.

**Cooldown:** default 60 seconds. Prevents back-to-back fires while you ladder out of a position.

**Example: take-profit watcher.**

```
What you set: Action = buy, cooldown = 60s.
When it fires: After every buy on any chain. The agent watches the new position and posts an alert when it hits +50% or -25%.
```

**Example: realized PnL log.**

```
What you set: Action = sell, cooldown = 30s.
When it fires: After every sell. The agent records entry, exit, hold time, and realized PnL to a log you can pull later.
```

<Warning>
  This trigger fires off your own wallet activity, not signals or alpha. To react to alpha calls or group mentions instead, see [Natural Language Trading](/agent-kit/nlp-overview).
</Warning>

## Allow API calls

Turning this on lets you invoke the agent from outside Shuriken. Same agent, same task prompt, same tools. The fire signal comes from your own webhook, script, or MCP client.

### REST

`POST /api/v2/agents/{agentId}/invoke`. Send a Bearer token from a key with the `invoke:agent` scope, a JSON body with the prompt, and an optional `await_result` flag. The optional `Idempotency-Key` header makes a retry safe: same key, same response, no duplicate session.

```bash theme={null}
curl -X POST https://api.shuriken.trade/api/v2/agents/$AGENT_ID/invoke \
  -H "Authorization: Bearer $SHURIKEN_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "prompt": "Run my morning briefing now",
    "await_result": true
  }'
```

To check on a session you started without awaiting, call `GET /api/v2/agents/sessions/{sessionId}/status`.

### MCP

The same surface is exposed as MCP tools to any MCP client, including Claude Desktop, Cursor, and Windsurf. Both tools require a key with the `invoke:agent` scope.

```ts theme={null}
// From a Claude Desktop or Cursor session connected to Shuriken MCP
await invoke_agent({
  agent_id: "ag_abc123",
  prompt: "Run a rug check on this contract: <addr>",
  await_result: true,
})

// Poll a long-running session
await get_agent_invocation_status({
  session_id: "sess_xyz789",
})
```

For keys that should *only* fire agents and nothing else, pick the **agent-invoker** playbook when you create the key. It bundles `invoke:agent` and the read scopes the agent needs to start, with no trade scope of its own.

### Rate limit

Set `max_per_minute` on the trigger (default 10). The endpoint returns `429` once you cross it. Useful for keys you embed in webhooks where a stuck loop could otherwise burn through your credit.

## Combining triggers

An agent can carry a schedule, a trade trigger, and an API trigger at the same time.

A research agent might run every morning on a schedule, fire after every buy you make for a quick post-trade sanity check, and also be callable on demand from your Claude Desktop session when you want a one-off. Each fire is its own session with its own transcript.

## Testing a trigger

The agent modal has a "Run" button in the top bar. It fires the agent once with a custom prompt, ignoring all triggers. Use it to sanity-check the task prompt before you turn triggers on. The session shows up in the same run history as a real fire.

## Get started

<CardGroup cols={2}>
  <Card title="Back to Labs" icon="flask" href="/agent-kit/labs/overview">
    Concept, run lifecycle, Stop button, credits and billing.
  </Card>

  <Card title="Permissions and safety" icon="shield-halved" href="/agent-kit/permissions">
    The full list of scopes, plus the per-trade and daily limits the agent runs under.
  </Card>
</CardGroup>