HiveSwap API

Stateless DEX and bridge API for Hive Engine. Returns unsigned custom_json ops and native Hive transfer ops; you sign with Hive Keychain (browser) or your own posting/active key (server). The API never sees private keys.

Quick facts

Base URL: https://api.hive-swap.com
Auth: none. Per-IP rate limit: 30 requests / minute.
Response envelope: { ok: true, data: ... } or { ok: false, error: { code, message } }.
CORS: Access-Control-Allow-Origin: * on every response.
Platform fee: 0.25% (25 bps) of input — collected by the first op the API returns. Don't strip it.
For LLM integrators: see /llms.txt and /llms-full.txt.

Endpoint index

GET /health — liveness probe
GET /tokens — all HE tokens
GET /pools — all liquidity pools
GET /gateways — bridge gateway info
POST /quote — swap quote
POST /swap/build — unsigned swap ops
POST /bridge/in/build — Hive → wHIVE / SWAP.HIVE
POST /bridge/out/build — peg-out → native HIVE
POST /bridge/converter/quote — BTC/LTC/DOGE/BCH ↔ SWAP.X
GET /bridge/converter/coins — converter coin list
GET /status/{ref} — bridge status
GET /profile/{username} — points profile + badges
GET /profile/{username}/activity — points history
GET /leaderboard — top users by total points
Tips for integrators — read this before broadcasting

Endpoints

GET/health

Liveness probe. Not rate limited.

Response

{ "ok": true, "data": { "status": "ok", "service": "hive-swap-api", "version": "v1", "time": "2026-05-11T..." } }

GET/tokens

All Hive Engine tokens with precision and icon.

Response

{ "ok": true, "data": { "tokens": [
  { "symbol": "BEE", "name": "BEE Token", "precision": 8, "issuer": "aggroed", "icon": "https://..." }
] } }

GET/pools

All marketpools liquidity pools.

Response

{ "ok": true, "data": { "pools": [
  { "tokenPair": "SWAP.HIVE:BEE", "baseQuantity": "...", "quoteQuantity": "...", "basePrice": "...", "quotePrice": "...", "totalShares": "..." }
] } }

GET/gateways

Bridge gateway info — HE peg, EVM, converter (BTC/LTC/DOGE/BCH), and HE-native (ETH/BSC/Polygon/Solana).

Response

{ "ok": true, "data": {
  "platformFeeBps": 25,
  "heGateways": [{ "account": "uswap", "label": "USWAP", "feePct": 0.09, "pegInMin": 1, "pegInSoftCap": 10000 }],
  "evmBridges": [{ "chain": "base", "hiveGateway": "whive.base", "minHive": 100, "minTotalHive": 100.26, "memoFormat": "bridge:hive-base:<0xEvmAddress>" }],
  "converterBridges": [
    { "coin": "BTC",  "swapSymbol": "SWAP.BTC",  "hiveGateway": "btc-swap", "minAmount": 0.0005, "converterApiBase": "https://...", "quoteEndpoint": "/api/v1/bridge/converter/quote", "memoFormat": "BTC <external-address>" },
    { "coin": "LTC",  "swapSymbol": "SWAP.LTC",  "hiveGateway": "btc-swap", "minAmount": 0.05,   "converterApiBase": "https://...", "quoteEndpoint": "/api/v1/bridge/converter/quote", "memoFormat": "LTC <external-address>" }
  ],
  "nativeBridges": [
    { "chain": "eth",     "coin": "ETH", "swapSymbol": "SWAP.ETH",   "hiveGateway": "swap-eth",     "gatewayApiBase": "https://...", "registrationId": "...", "withdrawalFeePct": 1.0, "memoFormat": "<destination-address>" },
    { "chain": "solana",  "coin": "SOL", "swapSymbol": "SWAP.SOL",   "hiveGateway": "swap-solana",  "gatewayApiBase": "https://...", "registrationId": "...", "withdrawalFeePct": 1.0, "memoFormat": "<destination-address>" }
  ]
} }

converterBridges and nativeBridgesadvertise gateway info for chain pegs that don't yet have a dedicated /build endpoint. For converter peg-in, call /bridge/converter/quote. For converter peg-out and all HE-native peg-out, sign a Hive Engine tokens.transfer of the SWAP.X token to hiveGateway with memoFormat as the memo — plus the 0.25% platform fee in a separate tokens.transfer to hive-swap-fees (same pattern as /bridge/out/build).

POST/quote

Get a swap quote. GET with query params is also accepted. The router searches the full pool graph (up to 3 hops) through any intermediate token, considers AMM pools and the Hive Engine order book on every leg, and may split a single hop between them when that improves price. Pass username to get a quote that's BEED-aware and matches what /swap/build will produce.

Request

{ "fromSymbol": "SWAP.HIVE", "toSymbol": "BEE", "amount": "10", "slippagePct": 1, "username": "alice" }

Response

{ "ok": true, "data": { "quote": {
  "route": [{
    "tokenIn": "SWAP.HIVE", "tokenOut": "BEE",
    "amountIn": "10", "amountOut": "...",
    "poolPair": "SWAP.HIVE:BEE",
    "poolPortion": { "amountIn": "6", "amountOut": "...", "poolPair": "SWAP.HIVE:BEE" },
    "bookPortion": { "amountIn": "4", "amountOut": "...", "side": "buy",
                     "worstPrice": "...", "limitPrice": "...",
                     "levelsConsumed": 3, "fullyFilled": true }
  }],
  "amountIn": "10", "amountOut": "...", "priceImpact": "0.0123", "minAmountOut": "..."
} } }

Each route step may carry poolPortion (AMM via marketpools), bookPortion (HE order book via market.buy/market.sell), or both (split route).

The top-level poolPair on a step is kept for backwards compatibility and mirrors poolPortion?.poolPair; new integrations should read the portions directly. bookPortion.limitPriceis the worst price you'll accept on the book leg — HE matches at the maker's price, not at limitPrice.

The router walks the pool graph up to 3 hops through any intermediate token and returns the route with the highest output after fees — that may be a longer path than the obvious direct one if an arbitrage route is more efficient, and pairs that previously failed because the target had no SWAP.HIVE pool (e.g. HSBIDAO) now route through whichever connector token has a path. Dead pools (zero reserves on either side) are filtered out. Order books still apply only to SWAP.HIVE-paired legs (HE protocol constraint), so multi-hop routes can layer in book depth on the hops that touch the hub.

Optional username.When supplied, the quote becomes BEED-aware: if the account holds < 0.002 BEED, book legs are stripped and a pool-only route is returned (the HE market.* contract burns 0.001 BEED per book action and the swap would otherwise revert at broadcast). Omit username to get the raw best-output route. Pass it when you want the quote to match what /swap/build will actually return for the same user.

Errors: NO_ROUTE (404) when no path within 3 hops connects the pair via pools and SWAP.HIVE-paired books. INVALID_INPUT when username is present but malformed.

POST/swap/build

Build the unsigned custom_json ops for a swap. Includes the 0.25% platform fee transfer as the first op. Ops can mix marketpools.swapTokens (pool portion) with market.buy / market.sell (book portion) when the router picks a split route.

Request

{ "username": "alice", "fromSymbol": "SWAP.HIVE", "toSymbol": "BEE", "amount": "10", "slippagePct": 1 }

Response

{ "ok": true, "data": {
  "quote": { ... },
  "ops": [
    { "contractName": "tokens",      "contractAction": "transfer",
      "contractPayload": { "symbol": "SWAP.HIVE", "to": "hive-swap-fees", "quantity": "0.025", "memo": "HiveSwap swap: SWAP.HIVE→BEE | r:a8f2c1", "isSignedWithActiveKey": true } },
    { "contractName": "marketpools", "contractAction": "swapTokens",
      "contractPayload": { "tokenPair": "SWAP.HIVE:BEE", "tokenSymbol": "SWAP.HIVE", "tokenAmount": "5.985",
                           "tradeType": "exactInput", "minAmountOut": "...", "isSignedWithActiveKey": true } },
    { "contractName": "market",      "contractAction": "buy",
      "contractPayload": { "symbol": "BEE", "quantity": "...", "price": "..." } }
  ],
  "signing": { "method": "requestCustomJson", "hiveChainId": "ssc-mainnet-hive", "keyType": "Active", "displayName": "...", "note": "..." }
} }

All ops sit in the same Hive custom_jsonand execute atomically. Intermediate hops use minimal slippage protection on the pool leg; the final hop carries the user's minAmountOut. Book legs enforce slippage per-leg via price (= bookPortion.limitPrice).

BEED multi-tx fee — auto-routed around. Hive Engine's market contract burns 0.001 BEED per market.buy/market.sell action (via resourcemanager). Without BEED, those ops revert at the burn step while the fee transfer op in the same Hive tx still succeeds — silently draining the user's input token. To prevent this, /swap/build checks the supplied username and strips book-routed legs when the account holds < 0.002 BEED, returning a pool-only build that has nomarket.* ops. No client-side handling required for the common case.

Edge case: no pool path exists. If the only route to toSymbol goes through the order book (rare — obscure tokens with no AMM liquidity), the API still returns the book route as a last resort. Detect by inspecting ops for any market.buy/market.sell after a build call. In that case the user must hold BEED — either acquire any small amount through an HE wallet, or prepend a beedollar.convert op yourself (1 BEE → ~39 BEED, 1% fee, 1 BEE chain min) in the same Hive tx. The web UI offers an in-app bootstrap; third-party integrations can do the equivalent.

POST/bridge/in/build

Build native Hive transfer ops to bridge HIVE to wHIVE on Base/BSC/Eth (type='evm'), or to peg into SWAP.HIVE via uswap/honey-swap (type='he').

Request

// EVM bridge:
{ "type": "evm", "username": "alice", "amount": "150", "toChain": "base", "toAddress": "0xabc..." }

// HE peg-in:
{ "type": "he",  "username": "alice", "amount": "5", "slippagePct": 1 }

Response

{ "ok": true, "data": {
  "gateway": "whive.base", "chain": "base",
  "ops": [
    ["transfer", { "from": "alice", "to": "hive-swap-fees", "amount": "0.375 HIVE", "memo": "HiveSwap peg-in: HIVE→Base | r:b7e3d2" }],
    ["transfer", { "from": "alice", "to": "whive.base",     "amount": "149.625 HIVE", "memo": "bridge:hive-base:0xabc..." }]
  ],
  "split": { "netAmount": "149.625", "feeAmount": "0.375", "totalAmount": "150.000", "feePct": 0.25 },
  "estimatedReceive": "149.625",
  "signing": { "method": "broadcastOps", "keyType": "Active", "displayName": "...", "note": "..." }
} }

These are native Hive transfer operations, not custom_json. Sign as a normal Hive transaction (broadcastOps in the SDK, or window.hive_keychain.requestBroadcast in the browser). Errors: BELOW_MIN if amount is below minTotalHive.

POST/bridge/out/build

Build custom_json ops for SWAP.HIVE → native HIVE peg-out via the hivepegged contract. SWAP.HIVE only — the contract is HIVE-only. The web UI also has a USWAP fast-path when that gateway has reserves; the API always returns the contract path.

Request

{ "username": "alice", "amount": "10" }

Response

{ "ok": true, "data": {
  "ops": [
    { "contractName": "tokens",     "contractAction": "transfer",
      "contractPayload": { "symbol": "SWAP.HIVE", "to": "hive-swap-fees", "quantity": "0.025", "memo": "HiveSwap peg-out: SWAP.HIVE→HIVE | r:c9a4b3" } },
    { "contractName": "hivepegged", "contractAction": "withdraw",
      "contractPayload": { "quantity": "9.975", "isSignedWithActiveKey": true } }
  ],
  "split": { "netAmount": "9.975", "feeAmount": "0.025", "totalAmount": "10.000", "feePct": 0.25 },
  "symbol": "SWAP.HIVE",
  "signing": { "method": "requestCustomJson", "hiveChainId": "ssc-mainnet-hive", "keyType": "Active", ... }
} }

POST/bridge/converter/quote

Register a peg-in (BTC/LTC/DOGE/BCH → SWAP.X) or peg-out (SWAP.X → BTC/LTC/DOGE/BCH) with the converter gateway. Peg-in returns a chain-specific deposit address; peg-out returns the HE account + memo to send SWAP.X to. No platform fee collected here — for peg-out the caller signs the SWAP.X transfer plus a 0.25% platform fee, same pattern as /bridge/out/build.

Request

// peg-in (external → Hive)
{ "fromCoin": "BTC", "toCoin": "SWAP.BTC", "destination": "alice" }

// peg-out (Hive → external)
{ "fromCoin": "SWAP.BTC", "toCoin": "BTC", "destination": "bc1q..." }

Response

// peg-in response
{ "ok": true, "data": {
  "destination": "alice",
  "address": "bc1q...",
  "gatewayAccount": "btc-swap"
} }

// peg-out response
{ "ok": true, "data": {
  "account": "btc-swap",
  "memo": "BTC bc1q...",
  "gatewayAccount": "btc-swap"
} }

Supported pairs only: fromCoin ∈ {BTC,LTC,DOGE,BCH} with toCoin = `SWAP.${fromCoin}` (peg-in), or the reverse (peg-out). For peg-in,destination must be a valid Hive account. For peg-out it must be a valid external address ≤128 chars (validated upstream). Errors: INVALID_INPUT for bad pair / destination; UPSTREAM (502) if the converter API is unreachable.

GET/bridge/converter/coins

Static list of converter-supported coins with chain minimums, gateway account, and memo format. Cache: s-maxage=300.

Response

{ "ok": true, "data": { "coins": [
  { "coin": "BTC",  "swap": "SWAP.BTC",  "displayName": "Bitcoin",      "precision": 8, "minAmount": 0.0005, "gatewayAccount": "btc-swap", "converterApiBase": "https://...", "platformFeeBps": 25, "memoFormat": "BTC <external-address>" },
  { "coin": "LTC",  "swap": "SWAP.LTC",  "displayName": "Litecoin",     "precision": 8, "minAmount": 0.05,   "gatewayAccount": "btc-swap", "converterApiBase": "https://...", "platformFeeBps": 25, "memoFormat": "LTC <external-address>" },
  { "coin": "DOGE", "swap": "SWAP.DOGE", "displayName": "Dogecoin",     "precision": 8, "minAmount": 50,     "gatewayAccount": "btc-swap", "converterApiBase": "https://...", "platformFeeBps": 25, "memoFormat": "DOGE <external-address>" },
  { "coin": "BCH",  "swap": "SWAP.BCH",  "displayName": "Bitcoin Cash", "precision": 8, "minAmount": 0.01,   "gatewayAccount": "btc-swap", "converterApiBase": "https://...", "platformFeeBps": 25, "memoFormat": "BCH <external-address>" }
] } }

HBD ↔ SWAP.HBD — web UI only

HBD bridging routes through DSwap and thegraphene-swap account. It is currently available only in the web UI at /bridge under the HBD tab.

There is no /bridge/hbd/* endpoint yet. Integrators that need HBD peg-in or peg-out must use the DSwap REST API directly at https://dswap-api.dswap.trade/api.

GET/status/{ref}

Bridge transaction status by reference. Same status pipeline backs the webhook-driven HE-native bridges (ETH/BSC/Polygon/Solana — see nativeBridges in /gateways) and the converter bridges (BTC/LTC/DOGE/BCH — see converterBridges).

Response

{ "ok": true, "data": { "reference": "...", "status": "pending|completed|failed", "direction": "...", "hops": [...], "createdAt": ..., "updatedAt": ... } }

Points, profiles, and leaderboard

Every successful swap and bridge earns the user Points. Swaps award 10 pts per $1 of input volume, bridges 15 pts per $1. Points are derived from on-chain fee events by replaying transaction logs — failed routes earn nothing (fee was paid, action didn't execute). New activity typically reflects on profiles within ~5 minutes.

Levels 1-30 are grouped into 6 tiers: Shrimp → Crab → Octopus → Dolphin → Shark → Whale. Threshold curve: floor(30 × (L-1)^3.8). Reaching L30 (Whale max) takes ~$1.08M lifetime volume.

Badges are computed at read time — adding a new badge applies retroactively and never requires a migration.

GET/profile/{username}

Points profile for a Hive user. Always succeeds — users with no activity return level 1 / 0 points / all badges locked.

Response

{ "ok": true, "data": {
  "username": "alice",
  "level": 12,
  "maxLevel": 30,
  "tier": { "id": "octopus", "name": "Octopus", "color": "#b85450" },
  "totalPoints": 312450,
  "pointsIntoLevel": 45753,
  "pointsToNext": 57250,
  "currentThreshold": 266697,
  "nextThreshold": 369902,
  "lifetimeVolumeUsd": 31245.7,
  "swapCount": 142,
  "bridgeCount": 8,
  "firstSeenTs": 1722470000,
  "lastActivityTs": 1747000000,
  "badges": [
    { "id": "tier_shrimp",  "label": "Shrimp",    "description": "Reach level 5",  "earned": true  },
    { "id": "tier_whale",   "label": "Whale",     "description": "Reach level 30", "earned": false },
    { "id": "first_swap",   "label": "First Swap","description": "Complete your first swap", "earned": true },
    { "id": "centurion",    "label": "Centurion", "description": "Complete 100 swaps", "earned": true }
  ],
  "leaderboardRank": 17
} }

Tier ceiling volumes (approx): Shrimp ~$582 · Crab ~$12.7k · Octopus ~$68k · Dolphin ~$218k · Shark ~$528k · Whale ~$1.08M. Badge IDs: tier_*, first_swap, centurion, first_bridge, cross_chain, megalodon ($10k+ event), kraken ($100k+ event), og.

GET/profile/{username}/activity

Paginated points-earning events for a user. Newest first. Pass ?before=<ts> for the next page.

Request

GET /profile/alice/activity?limit=25&before=1747000000

Response

{ "ok": true, "data": {
  "events": [{
    "opId": "67d8a3c1e9b8d4a000000123",
    "ts": 1747000000,
    "kind": "swap",
    "volumeUsd": 124.5,
    "pointsEarned": 1245,
    "symbol": "SWAP.HIVE",
    "amount": "0.305",
    "txId": "abc123...",
    "source": "he",
    "memo": null,
    "routeSteps": [{ "symbol": "SWAP.HIVE", "amount": "122.0" }, { "symbol": "BEE", "amount": "..." }]
  }],
  "nextBefore": 1747000000
} }

Failed swaps appear with volumeUsd: 0, pointsEarned: 0so they show up in history but don't earn points. routeSteps is best-effort — nullif the route couldn't be resolved.

GET/leaderboard

Top users by total points (all-time). Time-windowed variants (24h / 7d / 30d) are not yet supported.

Request

GET /leaderboard?limit=100

Response

{ "ok": true, "data": {
  "rows": [{
    "rank": 1,
    "username": "alice",
    "level": 27,
    "tier": { "id": "whale", "name": "Whale", "color": "#1e3a5f" },
    "totalPoints": 8104225,
    "lifetimeVolumeUsd": 810422.5,
    "swapCount": 412,
    "bridgeCount": 28,
    "lastActivityTs": 1747000000
  }],
  "total": 1247
} }

Signing the returned ops

Browser — Hive Keychain (custom_json)

for (const op of data.ops) {
  await new Promise((resolve, reject) => {
    window.hive_keychain.requestCustomJson(
      'alice',                  // username
      'ssc-mainnet-hive',       // chain id (always this for HE)
      'Active',                 // key type
      JSON.stringify(op),
      'HiveSwap',               // display label
      (r) => r.success ? resolve(r) : reject(new Error(r.message))
    );
  });
}

Each op produces one Keychain prompt. The SDK's broadcastOps wraps this loop.

Server — dhive (bundle into one tx)

import { Client, PrivateKey } from '@hiveio/dhive';
const client = new Client(['https://api.hive.blog']);

// Hive Engine ops (from /swap/build, /bridge/out/build):
const ops = data.ops.map(op => ['custom_json', {
  required_auths: ['alice'],
  required_posting_auths: [],
  id: 'ssc-mainnet-hive',
  json: JSON.stringify(op),
}]);

// Native bridge transfers (from /bridge/in/build) are already in [opName, payload] shape:
// const ops = data.ops;

await client.broadcast.sendOperations(ops, PrivateKey.fromString(process.env.HIVE_ACTIVE_KEY));

Error codes

Code	HTTP	Meaning
`INVALID_INPUT`	400	Missing or malformed parameter.
`NO_ROUTE`	404	No swap path within 3 hops.
`BELOW_MIN`	400	Bridge amount below the gateway minimum.
`NOT_FOUND`	404	Reference not found.
`RATE_LIMITED`	429	Per-IP limit exceeded. Includes `Retry-After`.
`UPSTREAM`	502	Hive / Hive Engine RPC unreachable.
`INTERNAL`	500	Unhandled error.

Tips for integrators

Always re-quote close to broadcast time. Pool reserves shift and book depth turns over fast; an old minAmountOut or bookPortion.limitPrice can be too tight and revert.
Book routes need BEED — but /swap/build auto-routes around it. When you call /swap/build with username (already required) the API strips book legs for accounts holding < 0.002 BEED and returns a pool-only build. Pass username to /quote too so the displayed quote matches. The only case to handle yourself is the rare pair with no pool path at all — detect by checking ops for market.* after build.
The platform fee is in the ops, not deducted by the API. The first op in every build response is the fee transfer to hive-swap-fees. Do not strip it — your effective output assumes it ran.
Bridge minimums are HARD. Sending below minTotalHive to a gateway can result in funds being permanently stuck (the gateway oracle ignores the transfer). The API enforces BELOW_MIN to prevent this — do not bypass it client-side.
Native vs custom_json ops are different shapes. /swap/build and /bridge/out/build return [{ contractName, contractAction, contractPayload }, ...] (Hive Engine custom_json). /bridge/in/build returns [[opName, payload], ...] (native Hive ops). Sign accordingly.
Chain id for HE ops is ssc-mainnet-hive. Always.

Changelog

v1.0 — Initial public API: tokens, pools, gateways, quote, swap/build, bridge in/out, status.
2026-05-11 — Clarified /bridge/out/build is SWAP.HIVE-only (the hivepegged contract is HIVE-only). HBD ↔ SWAP.HBD bridging (added to the web UI via DSwap / graphene-swap) is web-only — no API endpoint yet.
2026-05-12 — Added Points system: /profile/{username}, /profile/{username}/activity, and /leaderboard. 30 levels grouped into 6 tiers (Shrimp → Whale). Points derived from successful swap and bridge events.
2026-05-12 — Documented /bridge/converter/quote and /bridge/converter/coins (BTC/LTC/DOGE/BCH ↔ SWAP.X). Expanded /gateways response to include converterBridges and nativeBridges (ETH/BSC/Polygon/Solana) — these already shipped in the response but were missing from the docs.
2026-05-13 — /quote now accepts optional username for BEED-aware route selection. /swap/build automatically strips book-routed legs for accounts holding < 0.002 BEED on its already-required username, returning a pool-only build that doesn't revert at HE's market.* multi-tx fee. Prior behavior (build returning market.buy/market.sell ops that silently lose the platform fee on every retry for BEED-less users) is fixed.
2026-05-13 — Platform-fee transfer ops now carry typed memos so they're self-describing in Hive wallet history. Format: HiveSwap swap: A→B | r:XXXXXX for swap fees, HiveSwap peg-in: HIVE→Base | r:XXXXXX / HiveSwap peg-out: SWAP.X→Y | r:XXXXXX for bridge fees. The 6-hex r: ref is per-build random — useful for cross-referencing a wallet entry to a build response, not used by analytics. Integrators rendering the ops list can show the memo verbatim; integrators classifying transfers can match the HiveSwap swap / HiveSwap peg prefixes. Prior memo (HiveSwap platform fee on bridge ops, empty on swap ops) still classifies correctly for historical events.