# Lotus

> Lotus is directional liquidity and yield-bearing orders for Stellar: a Soroban range pool (lotus_pool) where a position only sells its inventory and never trades back, and a yield-bearing receipt (lUSDCb, minted 1:1 by lotus_vault against USDC lent on Blend through DeFindex) that can be quoted on the Stellar DEX. One order, four places to wait. Stellar testnet only, not audited.

Network: Stellar testnet (passphrase `Test SDF Network ; September 2015`). Market: LBOND / USDC, where LBOND is a simulated tokenized bond issued by the Lotus team (AUTH_REQUIRED, clawback). Trading volume comes from market-maker accounts run by the team, not from users.

Agents: check `GET https://lotus-stellar.vercel.app/api/health` first, read every contract id from `GET https://lotus-stellar.vercel.app/api/config` (never hard-code ids), and run vault-backed pool views and lotus_vault vault_value()/surplus() by simulation only. Every page below is raw Markdown; the same content is rendered for humans at https://lotus-stellar.vercel.app/docs.

## Docs

- [Overview](https://lotus-stellar.vercel.app/docs/overview.md): Lotus is directional liquidity and yield-bearing orders for Stellar. One order, chosen once, waits in one of four places. Everything runs on Stellar testnet; nothing is on mainnet and nothing is audited.
- [Concepts](https://lotus-stellar.vercel.app/docs/concepts.md): The directional range pool and its bins, the four places an order can wait, the receipt token and its redemption at par, the curator rule, and why orders are locked until filled.
- [Using the app](https://lotus-stellar.vercel.app/docs/using-the-app.md): A walk through every screen: get test tokens on /faucet, swap or place one-price and range orders on /swap, build a position across the four strategies on /pools, trade the SDEX books on /trade, and manage everything on /portfolio.
- [Contracts](https://lotus-stellar.vercel.app/docs/contracts.md): The lotus_pool ABI (v1), the lotus_vault interface, their errors and events, and the live testnet addresses read from the deployment config at request time.
- [Integrate](https://lotus-stellar.vercel.app/docs/integrate.md): Three ways to build on Lotus: the HTTP endpoints of this app, a TypeScript SDK, and an MCP server that lets AI agents (Claude Code, Codex, Cursor, ...) read the markets and build transactions. Testnet only.
- [Bots and volume](https://lotus-stellar.vercel.app/docs/bots-and-volume.md): The trades on the Lotus testnet markets come from accounts run by the Lotus team. They are real on-chain transactions, but it is market-maker volume, not user volume. The LBOND price is simulated.
- [FAQ](https://lotus-stellar.vercel.app/docs/faq.md): Short, honest answers to the questions judges and integrators ask. Everything described runs on Stellar testnet unless stated otherwise. Nothing is audited.

## API

- [GET /api/health](https://lotus-stellar.vercel.app/api/health): deployment check. Response: { status: "ok"|"degraded"|"down", checkedAt, app: { name, version, commit|null, env }, network: { name, passphrase }, rpc: { url, ok, latencyMs, latestLedger, status }, horizon: { url, ok, latencyMs, latestLedger }, contracts: [{ kind, id, contract, status, ok, instance, liveUntilLedger, read?: { method, ok, value|error }, explorer }], summary: { total, ok, failed[] } }. HTTP 200 for ok/degraded, 503 for down.
- [GET /api/config](https://lotus-stellar.vercel.app/api/config): deployment config, public keys only, read at request time. Response: { network, rpc, horizon, passphrase, lotusVault, underlying: { code, issuer, sac }, receipt: { code, issuer, sac }, rwa: { code, issuer }, defindexVault, blendPool, strategies: [{ id, label, status, lotusVault, underlying, receipt, defindexVault, blendPool, observed? }], pools: [{ id, label, status, contract, base, quote, vault|null, binStepBps, feeBps, supportsTwoWay, mock }], retiredPools, accounts: { name: G... }, sources, loadedAt }. Read contract ids from here, never hard-code them.
- [GET /api/faucet](https://lotus-stellar.vercel.app/api/faucet): faucet status. Response: { ok, testnet, enabled, assets: [{ role, code, amount, configured, source }] }.
- [POST /api/faucet](https://lotus-stellar.vercel.app/api/faucet): testnet tokens. Body: { "address": "G..." } (account must exist and hold the trustlines). Response: { ok, address, results: [{ role, code, amount, status: "sent"|"skipped"|"error", hash?, message? }], error? }. Errors 400 / 403 / 409 / 429 / 502. One claim per address and asset, 6 requests per 10 minutes per IP.

## Optional

- [Full documentation in one file](https://lotus-stellar.vercel.app/llms-full.txt): every page above, concatenated.
- SDK and MCP server: `sdk/README.md` and `mcp/README.md` in the Lotus repository (tools lotus_health, lotus_config, lotus_markets, lotus_orderbook, lotus_pools, lotus_quote_swap, lotus_positions, lotus_offers, lotus_build_*, lotus_faucet_claim, lotus_submit).