Docs › Build with Beluga

Developer quickstart

From zero to a tracked bridge order with a few HTTP calls. No keys, no SDK: plain JSON over HTTPS.

The integration shape

  1. Read pricesGET /api/compare for the bid, GET /api/quote for exchange quotes, GET /api/redeem for redemptions.
  2. Create the orderPOST /api/deposit (XMR → XMR2) or POST /api/withdraw (XMR2 → XMR). Store the returned id.
  3. Fund itSend XMR to depositAddress, or XMR2 to the redemption's own sendTo address, before expiresAt.
  4. Track to a final statePoll GET /api/order/:id until completed, expired or refunded.

1. Read prices

curl https://beluga-host/api/compare?amount=10

ours.bid is our USDC bid per XMR2; depth shows what 10 XMR fetch on each book. Fields: API reference.

2. Bridge XMR → XMR2

curl -X POST https://beluga-host/api/deposit \
  -H 'Content-Type: application/json' \
  -d '{"hlAddress":"0xYourHyperliquidAddress0000000000000000000"}'
# 201 {"id":"wbZ0ngxAbnS2","note":"deposit address is assigned within ~20 s; poll GET /api/order/:id"}

Poll the order until depositAddress is set (state awaiting_deposit), then send XMR to it within 120 minutes.

3. Redeem XMR2 → XMR

curl -X POST https://beluga-host/api/withdraw \
  -H 'Content-Type: application/json' \
  -d '{"xmrAddress":"4..."}'
# 201 {"id":"OaOLD1FE90c4","sendTo":"0x…","note":"send XMR2 to sendTo (this order's own address) in one transfer, within 120 min; …"}

sendTo is this order's own Hyperliquid address. Send XMR2 to it from any account with one Hyperliquid spot transfer. The payout is the amount received minus 1.0%.

4. Track it

curl https://beluga-host/api/order/wbZ0ngxAbnS2
# {"id":"wbZ0ngxAbnS2","kind":"deposit","state":"confirming","confirmations":4, …}

Poll every 10 seconds or slower. Stop at completed, expired or refunded; keep polling through review. Details: Order lifecycle.

Rules worth knowing

  • Show funding instructions exactly as returned. Never build a deposit address yourself.
  • Amounts in orders are integer strings in atomic units: Money & settlement.
  • Creating an order is not idempotent: Errors & retries.
  • One transfer per redemption; never reuse an old order's sendTo for a new redemption.
  • Order creation has per-visitor caps: above a few unpaid orders the answer is 428 with a Turnstile captcha.sitekey; repeat the request with its token as turnstile.