API and SDK

How your agent will ask Merlin before every trade.

Planned for v1

The API and SDK are not live yet. This page shows the planned design so you can prepare your agent. Names and fields may change before release.

The flow

Create an API key for your agent in the dashboard.
Before every trade, call merlin.check() with the token and amount.
If the decision is ALLOW, send the trade. If it is BLOCK, don't.

TypeScript SDK

import { Merlin } from "@merlin/sdk";

const merlin = new Merlin({ apiKey: process.env.MERLIN_API_KEY });

const check = await merlin.check({
  agentId: "agent_01",
  token: "0x1f9840a85d5af5bf1d1762f925bdaddc4201f984", // UNI
  amountEth: 0.4,
});

if (check.decision === "ALLOW") {
  await agent.swap(trade);
} else {
  console.warn("Blocked by Merlin:", check.reason);
}

REST API

POST https://api.merlinai.live/v1/check
Authorization: Bearer <MERLIN_API_KEY>
Content-Type: application/json

{
  "agentId": "agent_01",
  "token": "0x1f9840a85d5af5bf1d1762f925bdaddc4201f984",
  "amountEth": 0.4
}

Request fields

Field	Type	Description
`agentId`	string	The agent whose rules apply
`token`	string	Contract address of the token to buy
`amountEth`	number	Trade size in ETH

Response

{
  "decision": "BLOCK",
  "reason": "Would reach 2.3 ETH, over the 2 ETH cap",
  "checks": [
    { "rule": "kill-switch", "passed": true },
    { "rule": "allowlist",   "passed": true },
    { "rule": "max-trade",   "passed": true },
    { "rule": "daily-cap",   "passed": false },
    { "rule": "contract",    "passed": true }
  ]
}

Fail safe

If Merlin cannot be reached or does not answer in time, the SDK returns BLOCK. A missed trade is cheaper than a bad one.

Keeping keys safe

Keep your Merlin API key in a server-side environment variable, never in browser code.
Merlin never needs your agent's private key. Never send it.
Use one key per agent, so you can revoke one without affecting the others.

Dashboard Token