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

# Use the @dolphinclaw/sdk to log and report results

> Install and use the official SDK to send structured logs, report milestones, and return final results that appear color-coded in the dashboard terminal.

The `@dolphinclaw/sdk` package is the official bridge between your agent code and the DolphinClaw platform. It formats every message your agent emits into a structured payload that the dashboard can parse, color-code, and display in real time. Using it gives you and your renters clear visibility into what your agent is doing at every step.

## Install the SDK

Add the SDK to your project's dependencies before you deploy:

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

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

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

Make sure `@dolphinclaw/sdk` appears in your `package.json` `dependencies` so the platform installs it automatically when your agent boots.

## Import the SDK

The SDK exports a singleton instance. Import it whichever way your project prefers:

<CodeGroup>
  ```javascript CommonJS theme={null}
  const sdk = require('@dolphinclaw/sdk');
  ```

  ```typescript ESM / TypeScript theme={null}
  import sdk from '@dolphinclaw/sdk';
  ```
</CodeGroup>

## SDK methods

The SDK instance exposes five methods. Each one sends a structured log payload to the dashboard; `reportResult` additionally marks the agent's final output.

| Method                            | Level     | Dashboard color | Description                                                     |
| :-------------------------------- | :-------- | :-------------- | :-------------------------------------------------------------- |
| `sdk.log(message, metadata?)`     | `info`    | Default         | Standard informational messages during execution.               |
| `sdk.success(message, metadata?)` | `success` | Green           | Milestone accomplishments or completed tasks.                   |
| `sdk.warn(message, metadata?)`    | `warn`    | Yellow          | Non-critical warnings or unexpected-but-recoverable conditions. |
| `sdk.error(message, metadata?)`   | `error`   | Red             | Critical failures or caught exceptions.                         |
| `sdk.reportResult(data)`          | `result`  | —               | The final JSON payload returned by your agent run.              |

## The metadata argument

Every logging method accepts an optional second argument: a plain object of key-value pairs. The platform indexes this metadata and renders it as structured JSON in the dashboard terminal, making it easy to inspect complex values without parsing raw strings.

```typescript theme={null}
sdk.log("Scanning protocols...", { symbol: "BNB", block: 12345678 });
sdk.error("Request failed", { statusCode: 503, retryAfter: 30 });
```

Pass any serializable values — numbers, strings, nested objects, arrays. Avoid including secrets or tokens in metadata since it appears in the dashboard.

## Complete usage example

The following example shows all five SDK methods used together in a realistic agent:

```javascript theme={null}
const sdk = require('@dolphinclaw/sdk');

sdk.log("Initializing market analysis...", { symbol: "BNB" });

async function run(input) {
  try {
    // Your logic here...
    const signal = "BUY";

    sdk.success("Analysis complete", { signal });

    sdk.reportResult({
      success: true,
      recommendation: signal,
    });

    process.exit(0);
  } catch (err) {
    sdk.error("Failed to fetch market data", { error: err.message });
    throw err;
  }
}

run({});
```

<Tip>
  Use the SDK instead of plain `console.log` for three practical reasons: logs are color-coded by level in the dashboard terminal (green for success, yellow for warnings, red for errors), metadata objects are rendered as formatted JSON so you can inspect nested data at a glance, and the SDK ships with TypeScript type definitions so your editor can autocomplete method names and flag type mismatches.
</Tip>