API

How your agent asks Lorentz before every trade.

The flow

  1. Open the dashboard, connect the wallet that owns your agent and sign in.
  2. Set your rules, then create an API key on the API keys page. Copy it; it is shown once.
  3. Before every trade, call POST /v1/check with the token and amount.
  4. If the decision is ALLOW, send the trade. If it is BLOCK, don't.

REST API

curl -X POST https://www.merlinai.live/v1/check \
  -H "Authorization: Bearer $LORENTZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"token":"0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984","amountEth":0.4}'

Request fields

FieldTypeDescription
tokenstringContract address of the token to buy (Ethereum mainnet). WETH, USDC, USDT, DAI, WBTC, UNI and LINK also work by symbol.
amountEthnumberTrade size in ETH

The API key decides which agent's rules apply, so there is no agent field.

Response

{
  "decision": "BLOCK",
  "reason": "Would reach 2.3 ETH, over the 2 ETH cap",
  "checks": [
    { "id": "kill-switch", "label": "Kill switch", "passed": true, "detail": "Trading is active" },
    { "id": "allowlist", "label": "Token allowlist", "passed": true, "detail": "UNI is approved" },
    { "id": "max-trade", "label": "Max trade size", "passed": true, "detail": "0.4 ETH is within the 0.5 ETH limit" },
    { "id": "daily-cap", "label": "Daily spend cap", "passed": false, "detail": "Would reach 2.3 ETH, over the 2 ETH cap" },
    { "id": "contract", "label": "Contract check", "passed": true, "detail": "Verified, no red flags found" }
  ],
  "token": "0x1f9840a85d5af5bf1d1762f925bdaddc4201f984",
  "symbol": "UNI",
  "amountEth": 0.4,
  "spentTodayEth": 1.9,
  "contract": { "verified": true, "risk": "low", "flags": [], "summary": "Well-known token." }
}
FieldDescription
decisionALLOW or BLOCK
reasonThe first rule that failed, or “All five rules passed”
checksResult of every rule, so you can see everything that would have failed
spentTodayEthETH already allowed today (UTC), before this trade
contractThe token's contract report: verified, risk, flags and a short summary

An ALLOW counts towards today's spend cap, because Lorentz assumes your agent sends the trade it asked about.

TypeScript helper

Copy this into your agent. It has no dependencies and blocks the trade if Lorentz cannot be reached.

// lorentz.ts: copy into your agent (Node 18+). No dependencies.
const LORENTZ_URL = "https://www.merlinai.live/v1/check";

export type LorentzDecision = {
  decision: "ALLOW" | "BLOCK";
  reason: string;
  checks: { id: string; label: string; passed: boolean; detail: string }[];
};

/** Ask Lorentz before every trade. Fails safe: any error or timeout returns BLOCK. */
export async function lorentzCheck(token: string, amountEth: number): Promise<LorentzDecision> {
  try {
    const res = await fetch(LORENTZ_URL, {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.LORENTZ_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ token, amountEth }),
      signal: AbortSignal.timeout(60_000), // a new token's first scan can take a while
    });
    if (!res.ok) throw new Error(`Lorentz HTTP ${res.status}`);
    return (await res.json()) as LorentzDecision;
  } catch (e) {
    return { decision: "BLOCK", reason: `Lorentz unavailable: ${(e as Error).message}`, checks: [] };
  }
}

Then use it before every swap:

import { lorentzCheck } from "./lorentz";

// Ask Lorentz before every trade
const check = await lorentzCheck("0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984", 0.4); // UNI

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

Contract report only

GET /v1/contract/0x… returns Lorentz's report for a token without making or logging a trade decision. Use the same API key.

Errors

StatusMeaning
400Bad token or amount
401Missing, invalid or revoked API key
503Lorentz is not configured or temporarily unavailable

Fail safe

Treat anything other than a clear ALLOW as a block. If a token's contract cannot be checked, Lorentz itself answers BLOCK. A missed trade is cheaper than a bad one.

Keeping keys safe

  • Keep your Lorentz API key in a server-side environment variable, never in browser code.
  • Lorentz never needs your agent's private key. Never send it.
  • Revoke a key on the API keys page and it stops working immediately.