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

# Quickstart: Send your first trace to Mortem

> Create an agent in the Mortem dashboard, install the SDK, wrap your agent code in a session, and view the resulting trace — all in under five minutes.

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.

<Steps>
  <Step title="Create an agent in the dashboard">
    Open the [Mortem dashboard](https://mortem.dev/app/agents/new) and sign in. Click **Add agent** to open the onboarding wizard.

    The wizard walks you through four steps:

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

    <Warning>
      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**.
    </Warning>
  </Step>

  <Step title="Install the SDK">
    Add `@mortemlabs/sdk` to your TypeScript agent project.

    <CodeGroup>
      ```bash npm theme={null}
      npm install @mortemlabs/sdk
      ```

      ```bash pnpm theme={null}
      pnpm add @mortemlabs/sdk
      ```

      ```bash yarn theme={null}
      yarn add @mortemlabs/sdk
      ```
    </CodeGroup>

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

    ```bash .env theme={null}
    MORTEM_API_KEY=your_api_key_here
    MORTEM_AGENT_ID=your_agent_id_here
    MORTEM_VERIFY_TOKEN=your_verify_token_here
    ```

    <Note>
      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.
    </Note>
  </Step>

  <Step title="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.

    ```typescript agent.ts theme={null}
    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.

    <Tip>
      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.
    </Tip>
  </Step>

  <Step title="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.

    <CodeGroup>
      ```typescript Vercel AI SDK theme={null}
      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()
      }
      ```

      ```typescript OpenAI theme={null}
      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())
      ```

      ```typescript Solana theme={null}
      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")
      )
      ```
    </CodeGroup>

    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     |
  </Step>

  <Step title="Run your agent">
    Run your agent once with the verify token present:

    ```bash theme={null}
    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**.
  </Step>

  <Step title="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.

    ```bash .env theme={null}
    MORTEM_API_KEY=your_api_key_here
    MORTEM_AGENT_ID=your_agent_id_here
    # MORTEM_VERIFY_TOKEN is no longer needed
    ```

    <Warning>
      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.
    </Warning>
  </Step>

  <Step title="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
  </Step>
</Steps>

## What's next

<CardGroup cols={2}>
  <Card title="Core concepts" icon="book-open" href="/concepts">
    Understand sessions, events, and autopsies in depth before adding more instrumentation.
  </Card>

  <Card title="SDK sessions" icon="layer-group" href="/sdk/sessions">
    Learn all session methods, event builders, and how trace context propagation works.
  </Card>

  <Card title="Integration guides" icon="puzzle-piece" href="/guides/vercel-ai-sdk">
    Full walkthroughs for Vercel AI SDK, OpenAI, Anthropic, LangChain, and Solana.
  </Card>

  <Card title="SDK events" icon="bolt" href="/sdk/events">
    Record custom events and understand all six built-in event types.
  </Card>
</CardGroup>