Quickstart: Send your first trace to Mortem

This guide takes you from zero to a working trace in the Mortem dashboard. You’ll create an agent, install @mortemlabs/sdk, run a minimal instrumented session, and confirm that the trace appears. By the end, your bot is ready for full instrumentation.

Create an agent in the dashboard

Open the Mortem dashboard and sign in. Click Add agent to open the onboarding wizard.The wizard walks you through four steps:

Name your agent and choose an environment (devnet or mainnet).
Copy your API key and agent ID. The API key is shown in plaintext exactly once — copy it now.
Copy the verify token. This one-time token proves that you control the agent on the first run. You’ll remove it after verification.
The wizard stays open and polls until it detects your first trace. Keep this tab open while you complete the steps below.

The API key and verify token are displayed once and cannot be retrieved again. If you lose them before verifying, rotate the API key from Agent settings.

Install the SDK

Add @mortemlabs/sdk to your TypeScript agent project.

npm install @mortemlabs/sdk

pnpm add @mortemlabs/sdk

yarn add @mortemlabs/sdk

The onboarding wizard pre-fills the exact environment variable values for your agent. Copy them from the wizard into your .env file:

.env

MORTEM_API_KEY=your_api_key_here
MORTEM_AGENT_ID=your_agent_id_here
MORTEM_VERIFY_TOKEN=your_verify_token_here

Do not set MORTEM_INGEST_URL for cloud usage. The SDK defaults to https://ingest.mortem.dev. Only override this variable when running against a self-hosted stack.

Instrument your agent

Initialize the Mortem client and wrap your agent logic in a session. The following snippet is the minimal recommended pattern — copy it into your entry point and replace the placeholder comment with your agent’s logic.

agent.ts

import { Mortem } from "@mortemlabs/sdk"

const mortem = new Mortem({
  apiKey: process.env.MORTEM_API_KEY ?? "",
  agentId: process.env.MORTEM_AGENT_ID,
  verifyToken: process.env.MORTEM_VERIFY_TOKEN,
  environment: "devnet",
})

const session = await mortem.startSession({
  inputSummary: "Evaluate a Solana trade setup and optionally submit the swap",
  tags: ["swap", "devnet"],
})

try {
  const result = await session.run(async () => {
    // your agent code here
    return { ok: true }
  })
} catch (error) {
  await session.fail(error)
} finally {
  await mortem.close()
}

A few things to note about this pattern:

session.run(...) keeps Mortem’s async trace context active while your agent performs work. Without it, child LLM, tool, and Solana events won’t be associated with the trace.
session.run automatically calls session.complete() on success and session.fail(error) on an uncaught exception, so you don’t need to call those manually inside the callback.
mortem.close() in the finally block flushes any buffered events before the process exits. Always call it.
session.traceId (or equivalently, session.id) gives you the trace ID if you want to construct a direct dashboard link.

Set inputSummary to a human-readable description of what this agent run is attempting to do. It appears in the trace list and makes it much easier to identify specific runs when debugging.

Wrap your LLM clients and Solana connection

Pass your existing LLM client and Solana connection through Mortem’s wrappers so that every call is automatically captured as an event on the active trace. The wrappers are drop-in replacements — your agent code doesn’t change.

import { generateText } from "ai"
import { openai } from "@ai-sdk/openai"
import { Mortem } from "@mortemlabs/sdk"

const mortem = new Mortem({
  apiKey: process.env.MORTEM_API_KEY ?? "",
  agentId: process.env.MORTEM_AGENT_ID,
  verifyToken: process.env.MORTEM_VERIFY_TOKEN,
  environment: "devnet",
})

const tracedModel = mortem.wrapLanguageModel(openai("gpt-4o"))
const tracedTools = mortem.wrapTools(tools)

const session = await mortem.startSession({
  inputSummary: "Evaluate whether the bot should open a token position",
})

try {
  const result = await session.run(async () => {
    return generateText({
      model: tracedModel,
      tools: tracedTools,
      maxSteps: 5,
      prompt: "Should I swap 1 SOL for JUP right now?",
    })
  })
} catch (error) {
  await session.fail(error)
} finally {
  await mortem.close()
}

import OpenAI from "openai"
import { Mortem } from "@mortemlabs/sdk"

const mortem = new Mortem({
  apiKey: process.env.MORTEM_API_KEY ?? "",
  agentId: process.env.MORTEM_AGENT_ID,
  verifyToken: process.env.MORTEM_VERIFY_TOKEN,
  environment: "devnet",
})

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

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

const mortem = new Mortem({
  apiKey: process.env.MORTEM_API_KEY ?? "",
  agentId: process.env.MORTEM_AGENT_ID,
  verifyToken: process.env.MORTEM_VERIFY_TOKEN,
  environment: "devnet",
})

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

The full set of available wrappers is:

Method	Wraps
`mortem.wrapOpenAI(client)`	OpenAI client
`mortem.wrapAnthropic(client)`	Anthropic client
`mortem.wrapOllama(client)`	Ollama client
`mortem.wrapLanguageModel(model)`	Vercel AI SDK language model
`mortem.wrapTools(tools)`	Vercel AI SDK tool definitions
`mortem.wrapConnection(conn)`	Solana `Connection`
`mortem.langchainHandler()`	LangChain callback handler

Run your agent

Run your agent once with the verify token present:

npx tsx agent.ts

The SDK sends a batch to the ingest service containing the session start event. Because MORTEM_VERIFY_TOKEN is set, the ingest service marks your agent as verified on this first flush.Switch back to the onboarding wizard in the dashboard. Within a few seconds it will show your agent as connected and verified.

Remove the verify token

Once the wizard confirms verification, remove MORTEM_VERIFY_TOKEN from your environment and code. It is a one-time credential and has no effect after the first successful trace.

.env

MORTEM_API_KEY=your_api_key_here
MORTEM_AGENT_ID=your_agent_id_here
# MORTEM_VERIFY_TOKEN is no longer needed

Leave MORTEM_VERIFY_TOKEN set on the second run and the ingest service will silently ignore it — but it’s good hygiene to remove one-time credentials from your environment promptly.

View your trace in the dashboard

Open Agents in the dashboard and click your agent. You’ll see:

The live stream panel, which shows incoming trace batches in real time as your agent runs.
The trace list, which shows every completed run with its status, duration, token count, and cost.

Click any trace to open the trace detail view. There you can:

Step through the full event chronology in order
Inspect the payload of each LLM call, tool call, or Solana transaction
Read the AI-generated autopsy once analysis completes (usually within a few seconds of trace completion)
Share the trace via a public link for team review

What’s next

Core concepts

Understand sessions, events, and autopsies in depth before adding more instrumentation.

SDK sessions

Learn all session methods, event builders, and how trace context propagation works.

Integration guides

Full walkthroughs for Vercel AI SDK, OpenAI, Anthropic, LangChain, and Solana.

SDK events

Record custom events and understand all six built-in event types.

Get Started

SDK

Dashboard

Guides

Reference

Quickstart: Send your first trace to Mortem

What’s next

Core concepts

SDK sessions

Integration guides

SDK events

​What’s next

Core concepts

SDK sessions

Integration guides

SDK events

What’s next