Event types reference: llm_call, tool_call, solana_tx

Events are the individual observations that make up a trace. Each time your agent calls an LLM, invokes a tool, submits a Solana transaction, or reaches a decision point, Mortem records that moment as an event with a type, payload, timing, and status. The dashboard assembles these events into a chronological decision sequence you can replay and inspect.

How events work

Every event belongs to a session and is recorded through an EventBuilder. When you use the SDK wrappers (wrapOpenAI, wrapAnthropic, wrapConnection, and so on), events are captured automatically. For steps that wrappers do not cover, call session.beginEvent() directly.

// Begin an event — returns an EventBuilder
const event = session.beginEvent("custom", { step: "market-analysis" })

// ... do work ...

// Complete it with a result payload
event.complete({ payload: { decision: "buy", confidence: 0.87 } })

You can also use event.run() to wrap an async function and have the SDK complete or fail the event automatically:

const result = await event.run(async () => {
  return fetchMarketData(token)
})

Event statuses

Every completed event has a status:

Status	Meaning
`"ok"`	The event completed successfully.
`"error"`	The event failed. The `errorMessage` field is populated.

Call event.complete() to record status "ok", or event.fail(error) to record status "error".

Parent and child events

Nest events under a parent to represent hierarchical work — for example, a planning step that triggers several tool calls. Use options.parentEventId when calling session.beginEvent():

const planning = session.beginEvent("custom", { step: "planning" })

const lookup = session.beginEvent(
  "tool_call",
  { toolName: "fetchPrice" },
  { parentEventId: planning.id },
)
lookup.complete({ payload: { price: 142.5 } })

planning.complete({ payload: { decision: "proceed" } })

When you wrap LLM clients and tools with Mortem’s wrappers and call them inside session.run(), parent-child linking is handled automatically through async context. Manual parentEventId is only needed when you manage the nesting yourself.

Auto-captured event types

These event types are recorded automatically when you use the corresponding SDK wrapper. You do not need to call session.beginEvent() for them.

`llm_call`

Recorded whenever your agent calls a wrapped LLM — OpenAI, Anthropic, Ollama, or a Vercel AI SDK model. Captures the model name, token usage, and estimated cost. Captured by: mortem.wrapOpenAI(), mortem.wrapAnthropic(), mortem.wrapOllama(), mortem.wrapLanguageModel() Payload shape:

{
  model: string          // e.g. "gpt-4o", "claude-sonnet-4-20250514"
  usage: {
    promptTokens: number
    completionTokens: number
    totalTokens: number
  }
  costUsd: number        // estimated cost in USD
}

Example setup:

const openai = mortem.wrapOpenAI(new OpenAI())

// All completions made through this client are now traced automatically
const response = await openai.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Should I buy JUP?" }],
})

`tool_call`

Recorded whenever a wrapped tool is invoked by the LLM. Captures the tool name, the input the model sent, and the output your function returned. Captured by: mortem.wrapTools(), mortem.langchainHandler() Payload shape:

{
  toolName: string
  input: unknown    // arguments passed to the tool
  output: unknown   // value returned by the tool
}

Example setup:

import { generateText, tool } from "ai"

const tools = mortem.wrapTools({
  fetchPrice: tool({
    description: "Get the current token price",
    parameters: z.object({ token: z.string() }),
    execute: async ({ token }) => getPriceFor(token),
  }),
})

await session.run(() =>
  generateText({ model: tracedModel, tools, prompt: "What is the SOL price?" })
)

`solana_tx`

Recorded whenever a Solana transaction is sent through a wrapped connection. Captures the transaction signature and the lamports transferred. Captured by: mortem.wrapConnection() Payload shape:

{
  signature: string   // base-58 transaction signature
  lamports: string    // lamport amount as a numeric string (bigint-safe)
}

Example setup:

import { Connection } from "@solana/web3.js"

const connection = mortem.wrapConnection(
  new Connection("https://api.devnet.solana.com")
)

// Transactions sent through this connection are traced automatically
const signature = await connection.sendRawTransaction(rawTx)

Manual event types

These event types are not captured by wrappers. Record them yourself with session.beginEvent().

`x402_payment`

Record an x402 payment event — an HTTP 402-based micropayment made by your agent.

const payment = session.beginEvent("x402_payment", {
  amount: 5000,
  currency: "USDC",
  recipient: "merchant.sol",
})

// ... execute payment ...

payment.complete({
  payload: { txSignature: "5Kd3NBUAdUnhyzenEwVLy9pBKGKdVUXmH..." },
})

`mcp_call`

Record a Model Context Protocol tool call made by your agent.

const mcp = session.beginEvent("mcp_call", {
  tool: "read_resource",
  server: "market-data-mcp",
})

const result = await mcpClient.callTool("read_resource", { uri: "price://SOL" })

mcp.complete({ payload: { result } })

`custom`

Record any arbitrary step in your agent’s reasoning process. Use custom events to mark decisions, checkpoints, strategy evaluations, or any other named step that is meaningful for post-trade debugging.

const event = session.beginEvent("custom", { step: "market-analysis" })

// ... do work ...

event.complete({ payload: { decision: "buy", confidence: 0.87 } })

Give each custom event a descriptive step value in the initial payload. That label appears in the dashboard’s event timeline and makes it easy to identify exactly where an agent’s reasoning diverged from the expected path.

`BeginEventOptions`

Pass these as the third argument to session.beginEvent() to control timing, identity, and nesting.

string

Override the auto-generated event ID. Useful when you need to correlate this event with an external system identifier.

parentEventId

string | null

Nest this event under a parent event. Set to the parent EventBuilder.id. Pass null explicitly to make the event a root event even when called inside a parent context.

startedAt

Date

Backfill the event start time. Use this if the work already began before you called beginEvent.

`CompleteEventOptions`

Pass these to event.complete() to attach a result payload and override timing.

payload

JsonValue

The result or output of this event. Any JSON-serializable value is accepted. If omitted, the payload passed to beginEvent is used as-is.

status

string

default:"ok"

Override the completion status. Defaults to "ok". Pass "error" if the event represents a failure you want to mark explicitly without calling event.fail().

endedAt

Date

Override the event end time. Defaults to the moment complete() is called.

Get Started

SDK

Dashboard

Guides

Reference

Event types reference: llm_call, tool_call, solana_tx

How events work

Event statuses

Parent and child events

Auto-captured event types

`llm_call`

`tool_call`

`solana_tx`

Manual event types

`x402_payment`

`mcp_call`

`custom`

`BeginEventOptions`

`CompleteEventOptions`

​How events work

​Event statuses

​Parent and child events

​Auto-captured event types

​llm_call

​tool_call

​solana_tx

​Manual event types

​x402_payment

​mcp_call

​custom

​BeginEventOptions

​CompleteEventOptions

How events work

Event statuses

Parent and child events

Auto-captured event types

`llm_call`

`tool_call`

`solana_tx`

Manual event types

`x402_payment`

`mcp_call`

`custom`

`BeginEventOptions`

`CompleteEventOptions`