Hood Long
Robinhood Chain Open app
API & agent integration

Build a Hood Long frontend.
Without guessing.

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.

Production endpointhttps://hoodlong.com/functions/v1/trade-api
01

Agent integration contract

The permitted boundary is simple and deliberate.

Agents can inspect

Markets, prices, liquidity, pool state, wallet positions, activity, affordability, and transaction status.

Agents can prepare

Fill the visible ticket, request executable calldata, and open one or more human review screens.

Users must execute

Only the connected wallet may authorize preparation, approve the final review, sign, and broadcast a trade.

Never bypass the review:Do not ask users for private keys, do not custody signatures, and do not auto-submit prepared transaction data.
02

Frontend blueprint for coding agents

Start with the full guide, generate a client from OpenAPI, then prove the state machines with the acceptance suite.

1 · Read the build spec

llms-full.txt defines stores, wallet-session invariants, refresh cadence, open/close flows, lending calls, loading behavior, responsive layout, and release checks.

2 · Generate the client

openapi.json describes every supported public action. Validate responses at runtime and keep blockchain quantities as strings or big integers.

3 · Run acceptance tests

The guide includes 15 end-to-end scenarios covering stale wallets, insufficient funds, uncertain broadcasts, replacement transactions, charts, lending, and mobile UX.

Starter instruction for a coding agentCopy as context
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.
03

Network and contracts

Use decimal strings for user-entered amounts and hexadecimal quantities only inside the prepared transaction.

ChainRobinhood ChainChain ID 4663
Gas tokenETHGas is separate from collateral
Collateral assetWETH0x0Bd7…AD73

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.

04

Read markets and liquidity

Every response is JSON and contains ok: true on success.

JavaScriptNo API key required
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.

05

Open a position

A live opening uses one personal signature and one on-chain transaction.

  1. QuoteCall quote with market, collateral, leverage, direction, and wallet.
  2. Authorize preparationCall prepare_challenge with the exact same intent, then ask the connected wallet to sign the returned message.
  3. PrepareCall prepare with the challenge fields and signature. Continue only when preparation.ready is true.
  4. Human reviewShow the latest quote, route, fees, liquidation level, transaction value, and expiry. Require an explicit user action.
  5. Broadcast and recordSend the returned transaction through the user’s wallet, then call record with its hash.
Wallet-authorized preparationethers v6
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
});
Time-sensitive:The authorization lasts about two minutes; executable open preparations last about 45 seconds. Never reuse a challenge or silently retry a wallet submission.
06

Close a position

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.

  1. Find the positionCall positions for the wallet and select an open position ID.
  2. Sign the intentRequest prepare_challenge with wallet and positionId, then sign its exact message.
  3. Prepare the closeCall prepare_close. Display debt, estimatedCloseFee, topUpWeth, minimum WETH received, and expiry.
  4. Broadcast and recordAfter explicit approval, send 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.

07

Transaction states and recovery

The chain is authoritative; the API index makes pending and completed activity usable in the interface.

submittedminedconfirmed

Poll safely

Call transaction_status with the wallet and position ID or transaction hash. The service refreshes eligible pending records.

Handle replacement

If the wallet replaces a transaction, call record_replacement with both hashes. Never record the replacement as a second trade.

Retry recording

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.

08

Action reference

POST JSON to the single endpoint with one of these action values.

ActionRequired inputPurpose
healthService health
marketsTradable markets, network, and route readiness
market_pricesCompact current price feed
market_liquiditymarketIdDEX and pool capacity for one market
price_historymarketIdETH-quoted points or OHLC candles; intervals: continuous, 10m, 30m, 1h, 4h
pooloptional walletPublic lending state and optional lender balance
quotemarketId, direction, collateral, leverageIndicative economics and risk
prepare_challengeintent, wallet, capabilitySingle-use message for wallet authorization
prepareopen intent, challenge, signatureShort-lived executable opening transaction
prepare_closepositionId, wallet authorizationShort-lived executable closing transaction
positionswalletIndexed positions with on-chain risk views
activitywalletLatest 50 wallet activity records
recordwallet, marketId, preparationId, txHashBind an opening hash to its reviewed preparation
record_closewallet, positionId, preparationId, txHashBind a closing hash to its reviewed preparation
transaction_statuswallet plus position ID or hashReconcile confirmation state
record_replacementwallet, old and replacement hashesLink 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.

09

WebMCP for browser agents

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.

10

Errors, limits, and retries

Failures use { "ok": false, "error": "…", "details": … }.

400 · Invalid or stale input

Correct the request, refresh market data, or request a new challenge. Do not loop automatically.

403 · Feature disabled

The requested live path is unavailable. Keep the market or action disabled.

404 · Not found

Refresh markets or positions; the resource may no longer be active.

409 · State conflict

Usually an outdated client, expired state, paused borrowing, mismatched transaction, or already-closed position. Re-read state before retrying.

  • Debounce quotes and do not poll executable swap quotes; request them only when the user enters review.
  • Respect expiresAt, market limits, borrowing state, pool availability, wallet balance, and gas.
  • Never change to, data, or value in a prepared transaction.
  • Use a fresh challenge for every preparation. The wallet is limited to 12 preparations per minute.
  • Short execution is not available until a dedicated short adapter is deployed; rely on route readiness instead of assuming support.