Agents can inspect
Markets, prices, liquidity, pool state, wallet positions, activity, affordability, and transaction status.
Give a coding agent the API schema, wallet rules, trade state machines, lending contract flow, responsive requirements, and acceptance tests needed to build a compatible interface.
The permitted boundary is simple and deliberate.
Markets, prices, liquidity, pool state, wallet positions, activity, affordability, and transaction status.
Fill the visible ticket, request executable calldata, and open one or more human review screens.
Only the connected wallet may authorize preparation, approve the final review, sign, and broadcast a trade.
Start with the full guide, generate a client from OpenAPI, then prove the state machines with the acceptance suite.
llms-full.txt defines stores, wallet-session invariants, refresh cadence, open/close flows, lending calls, loading behavior, responsive layout, and release checks.
openapi.json describes every supported public action. Validate responses at runtime and keep blockchain quantities as strings or big integers.
The guide includes 15 end-to-end scenarios covering stale wallets, insufficient funds, uncertain broadcasts, replacement transactions, charts, lending, and mobile UX.
Build a new Hood Long frontend against https://hoodlong.com.
Read these sources completely before coding:
1. https://hoodlong.com/llms-full.txt
2. https://hoodlong.com/openapi.json
3. https://hoodlong.com/webmcp-tools.json
Implement the documented wallet, open, close, reconciliation, positions,
chart, lending, loading, error, and responsive state machines. Preserve the
human review boundary. Return the implementation, architecture note, typed
API client, and completed acceptance-test matrix. Do not claim live trading
works from mocks or quote-only tests.
Use decimal strings for user-entered amounts and hexadecimal quantities only inside the prepared transaction.
Treat the network object returned by markets as the runtime source of truth. Never ship a private RPC, 0x, Rialto, or price-provider key to a browser.
Every response is JSON and contains ok: true on success.
const API = "https://hoodlong.com/functions/v1/trade-api";
async function hoodLong(action, input = {}) {
const response = await fetch(API, {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ action, ...input })
});
const data = await response.json();
if (!response.ok || !data.ok) throw new Error(data.error || "API request failed");
return data;
}
const { markets, network, routes } = await hoodLong("markets");
const { liquidity } = await hoodLong("market_liquidity", {
marketId: markets[0].id
});
Only offer a market when it is returned by markets, borrowingPaused is false, and routes.long.executable is true. Refresh liquidity immediately before showing a maximum order size.
A live opening uses one personal signature and one on-chain transaction.
quote with market, collateral, leverage, direction, and wallet.prepare_challenge with the exact same intent, then ask the connected wallet to sign the returned message.prepare with the challenge fields and signature. Continue only when preparation.ready is true.record with its hash.const intent = {
wallet: await signer.getAddress(),
marketId,
direction: "long",
collateral: "0.01",
leverage: "2",
walletClientCapability: "native-value-v2"
};
const { challenge } = await hoodLong("prepare_challenge", intent);
const signature = await signer.signMessage(challenge.message);
const { quote, preparation } = await hoodLong("prepare", {
...intent,
challengeId: challenge.id,
challengeExpiresAt: challenge.expiresAt,
signature
});
if (!preparation.ready) throw new Error(preparation.reason);
if (Date.parse(preparation.expiresAt) <= Date.now()) throw new Error("Preparation expired");
// Only after the user approves your visible confirmation screen:
const tx = await signer.sendTransaction(preparation.transaction);
await hoodLong("record", {
wallet: intent.wallet,
marketId,
preparationId: preparation.preparationId,
txHash: tx.hash
});
Closing follows the same review boundary and may include a small ETH top-up when sale proceeds are not enough to repay debt and fees.
positions for the wallet and select an open position ID.prepare_challenge with wallet and positionId, then sign its exact message.prepare_close. Display debt, estimatedCloseFee, topUpWeth, minimum WETH received, and expiry.preparation.transaction and pass the hash to record_close.Close preparations expire in about 20 seconds. The API computes any required top-up and rejects a top-up above the protocol’s 1 ETH safety limit. Do not infer or override it client-side.
The chain is authoritative; the API index makes pending and completed activity usable in the interface.
Call transaction_status with the wallet and position ID or transaction hash. The service refreshes eligible pending records.
If the wallet replaces a transaction, call record_replacement with both hashes. Never record the replacement as a second trade.
record and record_close are idempotent by transaction hash. A network failure after broadcast may be retried with the same values.
Do not resubmit merely because indexing is delayed. Preserve the transaction hash, show an explorer link, and reconcile it until the API returns a terminal state.
POST JSON to the single endpoint with one of these action values.
| Action | Required input | Purpose |
|---|---|---|
health | — | Service health |
markets | — | Tradable markets, network, and route readiness |
market_prices | — | Compact current price feed |
market_liquidity | marketId | DEX and pool capacity for one market |
price_history | marketId | ETH-quoted points or OHLC candles; intervals: continuous, 10m, 30m, 1h, 4h |
pool | optional wallet | Public lending state and optional lender balance |
quote | marketId, direction, collateral, leverage | Indicative economics and risk |
prepare_challenge | intent, wallet, capability | Single-use message for wallet authorization |
prepare | open intent, challenge, signature | Short-lived executable opening transaction |
prepare_close | positionId, wallet authorization | Short-lived executable closing transaction |
positions | wallet | Indexed positions with on-chain risk views |
activity | wallet | Latest 50 wallet activity records |
record | wallet, marketId, preparationId, txHash | Bind an opening hash to its reviewed preparation |
record_close | wallet, positionId, preparationId, txHash | Bind a closing hash to its reviewed preparation |
transaction_status | wallet plus position ID or hash | Reconcile confirmation state |
record_replacement | wallet, old and replacement hashes | Link a wallet replacement without duplicating a trade |
For complete request schemas and examples, use the OpenAPI document. Numeric blockchain quantities returned inside routes and transactions are strings to preserve precision.
The Hood Long app registers tools from the live page when the browser supports WebMCP.
get_interface_stateassess_trade_affordabilitylist_marketsset_trade_ticketprepare_trade_reviewlist_positionsprepare_position_closesshow_viewget_lending_poolset_lending_depositset_lending_withdrawalget_capability_status
Prefer WebMCP when the user is already inside Hood Long: it preserves the visible UI, connected-wallet context, affordability checks, and confirmation queue. Prefer the HTTP API for your own application. The exact tool schemas are in webmcp-tools.json.
Failures use { "ok": false, "error": "…", "details": … }.
Correct the request, refresh market data, or request a new challenge. Do not loop automatically.
The requested live path is unavailable. Keep the market or action disabled.
Refresh markets or positions; the resource may no longer be active.
Usually an outdated client, expired state, paused borrowing, mismatched transaction, or already-closed position. Re-read state before retrying.
expiresAt, market limits, borrowing state, pool availability, wallet balance, and gas.to, data, or value in a prepared transaction.