# hive-swap

> Stateless DEX aggregator and bridge for Hive Engine. The HTTP API returns unsigned
> Hive `custom_json` payloads (and native Hive transfer ops for cross-chain bridges);
> the caller signs locally with Hive Keychain or a posting/active key and broadcasts.
> No private keys ever touch the API.

Base URL: https://api.hive-swap.com
Rate limit: 30 requests/min per IP. No API key required.
Response envelope: `{ ok: true, data: ... }` or `{ ok: false, error: { code, message } }`.

## Docs

- [API Reference](https://www.hive-swap.com/docs/api): full endpoint specs, signing examples, error codes
- [Health](https://api.hive-swap.com/health): liveness check
- [Tokens](https://api.hive-swap.com/tokens): all Hive Engine tokens (symbol, precision, icon)
- [Pools](https://api.hive-swap.com/pools): all liquidity pools (reserves, prices)
- [Gateways](https://api.hive-swap.com/gateways): bridge gateway info — HE peg + EVM + converter (BTC/LTC/DOGE/BCH) + HE-native (ETH/BSC/Polygon/Solana)

## Endpoints (build returns unsigned ops)

- `POST /quote`: `{fromSymbol,toSymbol,amount,slippagePct,username?}` → SwapQuote. Multi-hop graph routing through any intermediate token (up to 3 hops); per-leg can use an AMM pool (`poolPortion`), the HE order book (`bookPortion` — SWAP.HIVE-paired legs only), or both (split route — better price via ternary-search optimum). Best-of-N when a pair has multiple pools. **Optional `username` makes the route BEED-aware**: if the account has < 0.002 BEED, book legs are stripped and a pool-only route is returned (avoids the HE `market.*` multi-tx fee reverting the swap). Omit `username` for the raw best-output route.
- `POST /swap/build`: `{username,fromSymbol,toSymbol,amount,slippagePct}` → custom_json ops (mix of `marketpools.swapTokens` and `market.buy` / `market.sell`) + signing hint. Routes BEED-aware on the user's `username` — accounts without BEED automatically get a pool-only build so the `market.*` 0.001 BEED multi-tx fee never reverts the swap. If you want raw book inclusion regardless of BEED holdings, prepend a `beedollar.convert` op yourself (see `/llms-full.txt`). The first op is always the platform-fee `tokens.transfer` to `hive-swap-fees` with a typed memo (`HiveSwap swap: {in}→{out} | r:{ref6}`); bridge endpoints below emit analogous `HiveSwap peg-in:` / `HiveSwap peg-out:` memos.
- `POST /bridge/in/build`: `{type:'evm'|'he', username, amount, toChain?, toAddress?}` → bridge ops
- `POST /bridge/out/build`: `{username, amount}` → SWAP.HIVE → HIVE peg-out custom_json ops (HIVE-only)
- `POST /bridge/converter/quote`: `{fromCoin,toCoin,destination}` → deposit address (peg-in) or `{account,memo}` (peg-out) for BTC/LTC/DOGE/BCH ↔ SWAP.X. No `/build` endpoint yet — caller signs the SWAP.X transfer with the returned memo (peg-out) or funds the returned address externally (peg-in).
- `GET  /bridge/converter/coins`: supported converter coins with minimums, gateway account, and memo format.
- `GET  /status/{ref}`: bridge transaction status by reference. Backs the webhook-driven HE-native (ETH/BSC/Polygon/Solana) and converter (BTC/LTC/DOGE/BCH) flows.
- `GET  /profile/{username}`: user points profile — level, tier (Shrimp→Whale), total points, badges, leaderboard rank
- `GET  /profile/{username}/activity`: paginated points-earning events for a user (`?limit=25&before=<ts>`)
- `GET  /leaderboard`: top-N users by total points (`?limit=100`, max 500)

Points are awarded for swaps (10 pts / $1 volume) and bridges (15 pts / $1 volume), derived from on-chain fee events. Levels 1-30 grouped into 6 tiers; L30 (Whale) requires ~$1.08M lifetime volume.

HBD ↔ SWAP.HBD bridging (via DSwap / `graphene-swap`) is currently available only in the web UI
at https://www.hive-swap.com/bridge — there is no public API endpoint for it yet.

## Optional

- [llms-full.txt](https://www.hive-swap.com/llms-full.txt): full inlined endpoint reference for LLMs