Umbix docs: one checked plan per trade.

A trade idea in, a signable plan out.

Your app sends intent: what to trade, how much, from which wallet. The planner resolves the asset, prices it, picks a route, builds the steps, simulates them and judges the result. The planner holds no key, keeps no funds and has no endpoint that accepts a signature.

Your first plan in three moves.

Buy NVDA with 500 USDG from your wallet. The answer holds unsigned steps only; nothing is sent until your wallet signs.

curl -s https://umbix.xyz/api/trades/plan \
  -H 'content-type: application/json' \
  -d '{"side":"buy","symbol":"NVDA","quote":"USDG",
       "amountIn":"500","wallet":"0xYourWallet"}'

const reply = await fetch("https://umbix.xyz/api/trades/plan", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({
    side: "buy", symbol: "NVDA", quote: "USDG",
    amountIn: "500", wallet: account,
  }),
});
const plan: PlanAnswer = await reply.json();
if (plan.verdict === "block") throw new Error(plan.reasons[0].message);

// Your app owns the wallet client; the planner never sees a key.
for (const step of plan.transactions) {
  const hash = await wallet.sendTransaction({
    to: step.to, data: step.data, value: BigInt(step.value),
  });
  await publicClient.waitForTransactionReceipt({ hash });
}

No keys, open limits.

The routes need no account and no API key. Base path: /api on this site, CORS open for POST /api/trades/plan.

curl -s https://umbix.xyz/api/assets/NVDA

Try the decision path without spending.

There is no separate test network to sign up for. Three ways to see real answers without moving funds:

Confirm the share before touching a pool.

A ticker is accepted only when it is on the planner's list of official stock tokens and the token's runtime code still embeds Robinhood's stock-token beacon.

curl -s https://umbix.xyz/api/assets/NVDA

One field, three modes, one live.

The request takes privacy.mode. Confidentiality with auditability, not anonymity. Only public produces steps in this build.

"privacy": { "mode": "public" }

Asking for stealth or shielded returns PRIVACY_MODE_UNAVAILABLE with no steps, rather than a plan that pretends.

Five guards on every public plan.

Each guard covers a different way a trade can go wrong between the ticker and the signature.

Route, steps, evidence and verdict in one answer.

A well-formed request always gets a plan, even when the verdict is block.

{
  "side": "buy",
  "symbol": "NVDA",
  "quote": "USDG",
  "amountIn": "500",
  "wallet": "0xYourWallet",
  "slippageBps": 50,
  "privacy": { "mode": "public" }
}

{
  "verdict": "allow",
  "reasons": [
    { "code": "APPROVAL_NEEDED", "level": "info", ... },
    { "code": "EXECUTOR_ROUTER", "level": "info", ... }
  ],
  "asset":     { "symbol": "NVDA", "canonical": true, "halted": false, ... },
  "reference": { "priceUsd": 217.0, "tokenValueUsd": 217.17, "ageSec": 840 },
  "quote": {
    "venue": "Uniswap v3",
    "route": [ { "fee": 100, ... }, { "fee": 500, ... } ],
    "amountOut": "2.2982", "minOut": "2.2867", "deviationBps": 18
  },
  "transactions": [
    { "step": 1, "kind": "approval", "to": "0x5fc5…", "data": "0x095e…" },
    { "step": 2, "kind": "swap",     "to": "0xCaf6…", "data": "0x5ae4…" }
  ],
  "simulation": { "ran": true, "ok": true, "calls": [ ... ] },
  "deadline": 1792520400
}

Every verdict names its rule.

Let your code follow the verdict and the reason codes, never the wording of the messages.

Thresholds: cost over reference warns from 2% and blocks from 10%. A reference older than 6 hours warns. USDG counts as one dollar for this check.

What anyone can still see.

A public plan is an ordinary swap. A watcher of the chain can read all of this:

A small surface with plain answers.

Every route answers JSON. Amounts are exact decimal strings; raw integer amounts are strings too.

One fetch, no package to install.

There is no SDK. A dozen lines of fetch give you the whole API:

const reply = await fetch("https://umbix.xyz/api/trades/plan", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({
    side: "buy", symbol: "NVDA", quote: "USDG",
    amountIn: "500", wallet: account,
  }),
});
const plan: PlanAnswer = await reply.json();
if (plan.verdict === "block") throw new Error(plan.reasons[0].message);

Let an agent propose, never sign.

An AI agent can call the endpoint like any client and reason over the reason codes. Keep the wallet outside the agent.

curl -s https://umbix.xyz/api/trades/plan \
  -H 'content-type: application/json' \
  -d '{"side":"sell","symbol":"TSLA","quote":"ETH",
       "amountIn":"0.25","wallet":"0xYourWallet",
       "slippageBps":75,"deadlineSec":300}'

Because a block verdict carries no steps, an agent cannot pass on something the planner refused. Let a person or a wallet policy approve the rest.

Errors a program can handle.

Malformed requests get HTTP 400 with a code. A well-formed request always gets a plan; problems with the trade itself come back as reason codes.

Request errors include INVALID_JSON, INVALID_AMOUNT, INVALID_SIDE and UNKNOWN_FIELD (400) and BODY_TOO_LARGE (413). Going over the rate limit returns HTTP 429 with a retry-after header.

What the planner will not stretch to.

Each limit is deliberate; most protect you from a plan that looks fine and settles badly.

Confidentiality with auditability, not anonymity.

Umbix is a planning tool. It is not a way to hide funds from anyone with a lawful right to see them, and it will not be described as one.

• It does not sign, send, custody or hold anything, and never requests a private key or recovery phrase.
• It does not guarantee a fill: simulation reads one block, the market moves on.
• It does not give investment advice. Stock tokens track a share's price and carry no shareholder rights.
• It is not affiliated with Robinhood or Uniswap and only reads their public contracts.