Skip to content

API reference

Swap

Convert between USDC and nTZS.

post/api/v1/swap

Convert between USDC and nTZS

Responds as a Server-Sent Events stream so you can show progress through each leg: each data: line is a JSON object { status, message, txHash?, orderId?, error?, refundTxHash? }, ending in a terminal status such as FILLED or FAILED. Carry minOutput over from GET /v1/swap/rate: if the best fill is below it the swap is refused with 409 SLIPPAGE_EXCEEDED and nothing moves. Refusals before the stream starts are plain-text bodies, except SLIPPAGE_EXCEEDED, which is JSON.

Parameters

  • Idempotency-Keystringheader

    Optional, single-use: this does NOT replay. The first request with a key claims it for 24 hours; any later request with the same key, including a retry after an error or a timeout, answers 409 "already been used" and does nothing. After an ambiguous outcome, read the resource back; send a new key for a new request.

Request body

  • userIdstring (uuid)required
  • fromTokenstringrequired

    Token registry symbol, upper case and case-sensitive, e.g. USDC, USDT, NTZS.

  • toTokenstringrequired

    As fromToken; must differ from it.

  • amountnumberrequired

    In fromToken units.

  • fromChainstringdefault "base"

    basebnb

  • toChainstringdefault "base"

    basebnb

  • slippageBpsintegerdefault 100

    Without minOutput: how far below the best available LP a fallback LP may be. Never reduces the payout.

  • minOutputnumber

    A floor on what the user receives. Pass the minOutput from the rate you showed.

Responses

  • 200An SSE stream of progress events.
  • 400Plain text: missing fields, a non-positive amount, invalid slippageBps/minOutput, identical tokens, or an unsupported token.
  • 401Missing, empty, or invalid API key. No machine-readable code is returned.BareError
  • 403Plain text: the wallet is frozen.
  • 404Plain text: no such user (USER_NOT_FOUND), the user has no wallet yet, or no active pair for these tokens (NO_PAIR).
  • 409SLIPPAGE_EXCEEDED (JSON, with bestOutput and floor): re-fetch the rate and let the user re-confirm. Plain text otherwise: the Idempotency-Key was already used (IDEMPOTENCY_REPLAY), or a swap is already in progress for this wallet (SWAP_IN_PROGRESS).object
  • 429Rate limited. Respect Retry-After and back off exponentially.CodeError
  • 501Test keys get not_available_in_test_mode: this endpoint is not simulated in the sandbox. Use a live key.CodeError
  • 503Usually plain text: stale pricing, no maker for this pair, insufficient LP inventory, or the swap service is halted or unavailable. Nothing moved.
Request
curl -X POST "https://www.ntzs.co.tz/api/v1/swap" \
  -H "Authorization: Bearer $NTZS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "userId": "14e17d04-ec7f-4d99-91a3-dfbaca19fba1",
  "fromToken": "USDC",
  "toToken": "NTZS",
  "amount": 10000,
  "fromChain": "base",
  "toChain": "base",
  "slippageBps": 100
}'
get/api/v1/swap/rate

Current USDC/nTZS rate

Public, no API key required. Valid for roughly 30 seconds. Show this to the user before they confirm a swap; do not cache it past its validity. Throttled per source address (60/min by default): cache a quote for its expiresAt window rather than re-fetching per keystroke. liquidityUnknown: true means the solver balance behind lowLiquidity could not be read within the time budget of the quote; the price is unaffected.

Public, no API key required

Parameters

  • fromstringqueryrequired

    Token registry symbol, case-insensitive, e.g. USDC, USDT, NTZS.

  • tostringqueryrequired

    As from (case-insensitive registry symbol); must differ from it.

  • amountnumberqueryrequired
  • fromChainstringquery
  • toChainstringquery

Responses

  • 200The live rate.Show fields
    • fromstring
    • tostring
    • fromChainstring
    • toChainstring
    • amountnumber
    • midRatenumber

      TZS per USD.

    • bidBpsnumber
    • askBpsnumber
    • spreadBpsnumber
    • tzsBuyRatenumber
    • tzsSellRatenumber
    • protocolFeeBpsnumber
    • expectedOutputnumber

      What the user receives, in to units.

    • minOutputnumber

      Pass to POST /v1/swap as minOutput.

    • ratenumber

      expectedOutput / amount.

    • expiresAtstring (date-time)
    • lowLiquidityboolean
    • quotedBystring

      self_custody when a maker's signed order priced this quote; textile when external liquidity covers a sale of nTZS for USDC that the pool cannot (the swap then takes a firm quote and streams a QUOTING status first).

    • liquidityUnknownboolean
  • 400Missing parameters, a non-positive amount, an unsupported token pair, or an unknown chain.CodeError
  • 404No active pair for this token combination.CodeError
  • 429Rate limited. Respect Retry-After and back off exponentially.CodeError
  • 503Pricing is temporarily unavailable. Retry shortly.CodeError
Request
curl "https://www.ntzs.co.tz/api/v1/swap/rate?from=USDC&to=NTZS&amount=5"
Response · 200
{
  "from": "…",
  "to": "…",
  "fromChain": "…",
  "toChain": "…",
  "amount": 10000,
  "midRate": 1,
  "bidBps": 1,
  "askBps": 1,
  "spreadBps": 1,
  "tzsBuyRate": 10000,
  "tzsSellRate": 10000,
  "protocolFeeBps": 10000,
  "expectedOutput": 1,
  "minOutput": 1,
  "rate": 1,
  "expiresAt": "2026-10-27T09:00:00Z",
  "lowLiquidity": true,
  "quotedBy": "…",
  "liquidityUnknown": true
}