Developer integration

01POST /api/quote

Send strict JSON: tokenIn/tokenOut from ETH, WETH or USDG, positive decimal amount string and slippage from 0.1 to 3 percent. Identical tokens, extra fields and invalid precision are rejected. Amount is at most eighty characters and must fit uint256.

No wallet address is needed. The following TypeScript uses the existing route; parse success bodies with the repository schema before using them.

type Token = 'ETH' | 'WETH' | 'USDG';
const request: { tokenIn: Token; tokenOut: Token;
  amount: string; slippage: number } = {
  tokenIn: 'ETH', tokenOut: 'USDG', amount: '0.001', slippage: 0.5,
};
const response = await fetch('/api/quote', {
  method: 'POST', headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(request),
});
const body: unknown = await response.json();
if (!response.ok) throw new Error('Quote unavailable');
// In this repository: quoteSchema.parse(body) validates success.

02Response and validation contract

MarketQuote contains chainId 4663, kind market/wrap, inputSymbol/outputSymbol, tokenIn/tokenOut, amountIn, amountOut, minimumOut, fee, pool, priceImpact, router, created, expiresIn 30, slippage, blockNumber, blockTimestamp and deadline. Amounts and block quantities are decimal integer strings; use BigInt, not Number. Address fields are hex strings. created is server milliseconds.

X-Quote-Served-At is server service time in milliseconds; Cache-Control is no-store. localizeQuote charges cache age and browser elapsed time before validateQuote binds request parameters. requestQuote already performs schema parsing, timing and validation. There is no /api/validate or /api/risk endpoint.

// Internal repository helpers; not a separately published SDK.
import { requestQuote } from '@/lib/quote-request';
import { validateQuote } from '@/lib/market';
import { amountUnits } from '@/lib/protection';
const abort = new AbortController();
const q = await requestQuote({
  input: 0, output: 2, amount: '0.001', slippage: 0.5,
}, abort.signal);
validateQuote(q, 'ETH', 'USDG', amountUnits('0.001', 18), 0.5);
// Market data is not permission to send.

03Health and errors

GET /api/health reports chainId, block and configured-contract code checks. walletActionsEnabled is false and walletSecurityReview is paused during this release. Infrastructure health does not imply wallet clearance or pool liquidity. RPC failure returns 503.

Quote 400 means malformed JSON, invalid schema/pair/amount. A 503 means route/RPC unavailable with error and reason. The browser prefers reason, then error, then fallback. Do not fabricate a quote on failure. Abort obsolete requests with AbortSignal; the server checks cancellation before/after quote work.

04Internal preparation response

prepareExecution(client, quote, address) is an internal RPC helper, not an HTTP endpoint. It returns account, created, payload, transaction, gas, fee, balance, eth, needsApproval, simulation and allowanceValid. BigInt values need explicit conversion for JSON. payload is the swap/wrap call; transaction may instead be an approval.

verifySession checks wallet chain/accounts. The engine re-prepares and enforces the gate before sending. Successful preparation is not a wallet interaction, broadcast or receipt.

05Environment and local operation

Use Node.js 24 and npm ci with the lockfile. Run npm run typecheck, npm run lint, npm test and npm run build. npm run dev starts the local interface. .npmrc uses legacy-peer-deps for this graph.

Server RPC_URL defaults to the public Robinhood endpoint; browser transport uses the public endpoint. No external quote key is required. RPC needs chain ID, block, code, eth_call, balances, gas price and estimateGas. Diagnostic simulation methods can require additional RPC support.

Never commit .env, Vercel credentials, seeds or keys. NEXT_PUBLIC values are public. Keep credentialed RPC URLs server-side. No environment variable bypasses the wallet release policy.