API reference
Swap
Convert between USDC and nTZS.
/api/v1/swapConvert 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-KeystringheaderOptional, 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)requiredfromTokenstringrequiredToken registry symbol, upper case and case-sensitive, e.g.
USDC,USDT,NTZS.toTokenstringrequiredAs
fromToken; must differ from it.amountnumberrequiredIn
fromTokenunits.fromChainstringdefault "base"basebnbtoChainstringdefault "base"basebnbslippageBpsintegerdefault 100Without
minOutput: how far below the best available LP a fallback LP may be. Never reduces the payout.minOutputnumberA floor on what the user receives. Pass the
minOutputfrom 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). - 409
SLIPPAGE_EXCEEDED(JSON, withbestOutputandfloor): re-fetch the rate and let the user re-confirm. Plain text otherwise: theIdempotency-Keywas already used (IDEMPOTENCY_REPLAY), or a swap is already in progress for this wallet (SWAP_IN_PROGRESS).object - 429Rate limited. Respect
Retry-Afterand 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.
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
}'/api/v1/swap/rateCurrent 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
fromstringqueryrequiredToken registry symbol, case-insensitive, e.g.
USDC,USDT,NTZS.tostringqueryrequiredAs
from(case-insensitive registry symbol); must differ from it.amountnumberqueryrequiredfromChainstringquerytoChainstringquery
Responses
200The live rate.Show fieldsHide
fromstringtostringfromChainstringtoChainstringamountnumbermidRatenumberTZS per USD.
bidBpsnumberaskBpsnumberspreadBpsnumbertzsBuyRatenumbertzsSellRatenumberprotocolFeeBpsnumberexpectedOutputnumberWhat the user receives, in
tounits.minOutputnumberPass to POST /v1/swap as
minOutput.ratenumberexpectedOutput / amount.expiresAtstring (date-time)lowLiquiditybooleanquotedBystringself_custodywhen a maker's signed order priced this quote;textilewhen external liquidity covers a sale of nTZS for USDC that the pool cannot (the swap then takes a firm quote and streams aQUOTINGstatus 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-Afterand back off exponentially.CodeError - 503Pricing is temporarily unavailable. Retry shortly.CodeError
curl "https://www.ntzs.co.tz/api/v1/swap/rate?from=USDC&to=NTZS&amount=5"{
"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
}