API integration

The swap API is public JSON under a versioned base—production usually looks like https://api.navoswap.com/api/v1. If you want credit in your partner dashboard and affiliate payout when the trade completes, attach your partner API key on POST /swap/create.

Attribution header

On POST https://api.navoswap.com/api/v1/swap/create, include:

x-navoswap-api-key: <your_partner_api_key>

The backend resolves the key to a partner record. If affiliate is enabled and a commission rate is set, the order stores your partner ID; when status reaches completed, commission accrues to your ledger (see Affiliate & payouts).

HTTP API overview

Everything hangs off https://api.navoswap.com/api/v1. The public swap app uses the same root via NEXT_PUBLIC_API_URL.

Two surfaces

Public swap & assets

• GET /assets — Tradable assets (params, networks, maintenance flags).
• GET /swap/quote — Indicative quote.
• POST /swap/create — Create order; optional x-navoswap-api-key.
• GET /swap/status — Order snapshot.
• GET /analytics/public — Platform-wide metrics (no auth; optional days query, typically 7–90).

Partner account (JWT)

/partners/… covers signup through 2FA, keys, orders, analytics, logout, and /partners/affiliate/… for balances, ledger, payouts, webhooks, CSV, and audit. Header: Authorization: Bearer <access_token>. Sign-in flows and profile routes are listed on the Program overview.

Swap REST endpoints

Prefix paths with https://api.navoswap.com/api/v1.

GET /swap/quote

Query parameters:

• currency_from, currency_to (required): Asset params from the catalog (e.g. BTC, USDTETH).
• amount_from: Float-rate flow (amount you send).
• amount_to: Fixed-rate flow together with fixed=true.
• is_anonym: Optional boolean for privacy-oriented routing when supported.
• fixed: Optional boolean; fixed-rate mode.

Response wraps a data object with indicative amount_from, amount_to, min/max bounds, optional USD fields, and timing hints.

POST /swap/create

JSON body (CreateSwapDto):

• currency_from, currency_to (string)
• address_to (string): Destination address
• amount_from or amount_to (number, optional): Float vs fixed
• receiver_memo_tag (string, optional)
• is_anonym (boolean, optional)
• fixed (boolean, optional)
• source (number, optional)

Send x-navoswap-api-key to attribute the order. Successful responses include order_info (public order id) for status polling.

GET /swap/status

Query: order_id. Returns latest order fields (status code, amounts, addresses, flags, creation time).

GET /swap/usd

Query: currency_from, amount_from. Server-side USD reference for the from leg; not a trade guarantee.

JavaScript SDK

We publish @navoswap/sdk with a typed NavoSwapClient around the public API. It uses fetch—Node 18+, browsers, edge workers, anywhere fetch exists.

Install

npm install @navoswap/sdk

Construction

Pass apiKey in the constructor; the client adds x-navoswap-api-key only on createSwapOrder.

import { NavoSwapClient } from "@navoswap/sdk";

const client = new NavoSwapClient({
  baseUrl: "https://api.navoswap.com/api/v1",
  apiKey: process.env.NAVOSWAP_PARTNER_API_KEY,
});

const quote = await client.getSwapPrice({
  currency_from: "BTC",
  currency_to: "ETH",
  amount_from: 0.1,
});

const order = await client.createSwapOrder({
  currency_from: "BTC",
  currency_to: "ETH",
  amount_from: 0.1,
  address_to: "0x…",
  fixed: false,
});

Methods

• getSwapPrice(params) — GET /swap/quote
• createSwapOrder(body) — POST /swap/create (adds API key header when configured)
• getSwapStatus(order_id) — GET /swap/status
• listAssets(network?) — GET /assets
• getPublicAnalytics(days?) — GET /analytics/public

Failed calls raise NavoSwapApiError with status and parsed JSON when available. Types CreateSwapOrderInput, SwapQuote, SwapOrderInfo, and AssetInfo match the REST shapes above.