API
How your agent asks Lorentz before every trade.
The flow
- Open the dashboard, connect the wallet that owns your agent and sign in.
- Set your rules, then create an API key on the API keys page. Copy it; it is shown once.
- Before every trade, call
POST /v1/checkwith the token and amount. - If the decision is
ALLOW, send the trade. If it isBLOCK, 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
| Field | Type | Description |
|---|---|---|
token | string | Contract address of the token to buy (Ethereum mainnet). WETH, USDC, USDT, DAI, WBTC, UNI and LINK also work by symbol. |
amountEth | number | Trade 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." }
}| Field | Description |
|---|---|
decision | ALLOW or BLOCK |
reason | The first rule that failed, or “All five rules passed” |
checks | Result of every rule, so you can see everything that would have failed |
spentTodayEth | ETH already allowed today (UTC), before this trade |
contract | The 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
| Status | Meaning |
|---|---|
| 400 | Bad token or amount |
| 401 | Missing, invalid or revoked API key |
| 503 | Lorentz 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.