# XLMarket — token launchpad on the Stellar network (XLM)

> Launch and trade tokens on Stellar: fair launches, locked liquidity, fixed
> supply, and existing XLM assets (AQUA, SHX, USDC…). A 1% trade fee plus a fixed
> launch fee fund the platform. Designed to be usable by humans AND autonomous
> AI agents.

This file helps AI agents understand and transact with the platform.
Machine-readable API: /openapi.json (OpenAPI 3.1 — generate an MCP server or
client from it). All endpoints return JSON.

STATUS: every READ endpoint below is open — no key, no signup, no beta code. They
return public Stellar ledger data, so there is nothing to gate.

WRITES are still in a private beta: /api/trade/build, /api/submit, /api/upload,
/api/intent/challenge and /api/launch/* answer 401 without a beta pass. Their
shapes are stable and will not change when that opens, so build against them now.

## How an agent transacts (no custody by us)
1. The agent holds its own Stellar keypair (or a managed in-browser wallet).
2. It calls a `build` endpoint to get an UNSIGNED transaction (base64 XDR).
3. It signs the XDR locally with its key.
4. It submits the signed XDR via `/api/submit`.
We never hold the agent's key; the 1% fee is included in the built transaction.

## What a launch guarantees
Every token launched here is issued by an account that is BLACKHOLED once minting
finishes: its signing weight is set to zero, permanently. That single fact is
machine-verifiable and carries two guarantees worth checking before you trade:
  • supply can never be increased — no account can mint more;
  • liquidity can never be withdrawn — the issuer holds the pool shares and can
    no longer sign, so neither the creator nor the platform can pull it.
Confirm both with /api/tokens/{id}/verify rather than trusting this file.
Every issuer is created on-chain by the published XLMarket launcher account,
which is how you tell a genuine launch from an imitation.

## Read endpoints (public, GET)
- /api/config — network, economics (fees)
- /api/tokens — tokens launched here (default). ?scope=all also returns existing
  Stellar assets (ids prefixed `ext-`), so you can trade AQUA/SHX/USDC etc.
- /api/tokens/{id} — one token + metrics
- /api/tokens/{id}/trades — recent trades, for launches here and for existing
  Stellar assets (those read the whole DEX by asset pair)
- /api/tokens/{id}/candles?interval=60 — OHLC candles
- /api/tokens/{id}/verify — on-chain legitimacy checks (launched-here tokens only;
  returns 404 for `ext-` assets — verify those on stellar.expert instead)
- /api/portfolio?account={G...} — holdings for an account
- /api/external/search?q={query} — find any existing Stellar asset

## Trade (POST)
- /api/trade/build  { tokenId, side: "buy"|"sell", amount, slippageBps, traderAccount }
    -> { xdr, estimatedOut, minReceived, feeXlm, priceImpactPct }
- /api/submit  { xdr }  -> { hash, successful }   # submit the signed xdr

## Authorization (signed intent) — REQUIRED for launch
Naming a public address is not a credential. Before /api/launch/prepare will act
for an account, prove you control it:
1. POST /api/intent/challenge  { purpose: "launch", input }
   where `input` is the EXACT body you will send next. -> { xdr, expiresIn }
2. Sign `xdr` with the account (it is a SEP-10-style challenge: sequence 0, so it
   can never execute on-chain; it only proves control). Any Stellar wallet can.
3. Send the same body plus  intentXdr: <signed xdr>  within 5 minutes.
The digest inside the challenge binds your signature to those exact parameters;
a replayed or altered request is rejected.

## Launch a token (POST)
- /api/launch/prepare  { name, ticker, totalSupply, devAllocationPct,
    initialLiquidityXlm, creatorAccount, ... } -> { jobId, issuer, xdr, requiredXlm }
- (sign + submit the pre-step xdr, which pays the launch fee and the liquidity
  in one payment)
- /api/launch/finalize { jobId, txHash } -> live token record

## Notes for agents
- Write endpoints (launch/trade/submit) are idempotent and rate limited per IP.
  Read endpoints are cheap and generally uncapped, but treat 429 as retryable
  with backoff — limits tighten as usage grows.
- Errors return { error: string }. Slippage is enforced via destMin.
- Trade fees are attached to the built transaction; nothing is charged separately.
- Verify a token with /api/tokens/{id}/verify before trading it.
- Automated clients are bound by the Terms of Use (/terms) like any other user,
  and the Risk Disclosure (/risk) describes what can go wrong. Launches and
  trades are irreversible once the signed transaction is submitted.