Products
Swap: nTZS / USDC / USDT
Execute a swap for any WaaS user. Supports nTZS, USDC, and USDT on Base, plus cross-chain USDT swaps via BNB Smart Chain. Streams status in real time over SSE.
Supported pairs
nTZS ↔ USDC, nTZS ↔ USDT (Base), USDT BNB ↔ nTZS cross-chain
Settlement
Two on-chain ERC-20 transfers, ~5–10 seconds same-chain
Gas
Auto-managed; user wallet pre-funded via relayer
What the user receives: exactly
expectedOutput, re-priced at the mid-rate in force when the swap runs. Slippage is never deducted. It is a floor. Pass the quote's minOutput and, if the price has moved below it, the request is refused with 409 { error: "SLIPPAGE_EXCEEDED" } before any funds move. Without minOutput, slippageBps bounds how far below the best available liquidity provider a fallback provider may be. Re-fetch the rate and let the user re-confirm before retrying.External liquidity: when our pool cannot cover a sale of nTZS for USDC on Base, the swap may be filled on an external venue instead of being refused. The rate then says
quotedBy: "textile", and the stream starts with a QUOTING event while a firm price is taken. If that price is unavailable or below your minOutput, the stream ends FAILED before any funds move (VENUE_NO_QUOTE, VENUE_QUOTE_REFUSED or SLIPPAGE_EXCEEDED). If the external fill fails after the deposit, the deposit is sent back and the stream ends VENUE_FILL_FAILED with a refundTxHash. In the rare case the external fill was sent but its outcome cannot be confirmed, it ends VENUE_FILL_UNCERTAIN: the deposit is held, not refunded, until support reconciles it, so do not retry.Retries: send an
Idempotency-Key. A key that has already been used answers 409 instead of swapping twice; a second swap for the same wallet while one is in flight also answers 409. Throttling answers 429 with Retry-After; a halted service or a stale rate answers 503.Balance after swap: Call
GET /api/v1/users/:id after FILLED. It returns live on-chain balances for nTZS, USDC, and USDT with no caching.POST /api/v1/swap (SSE stream)
const res = await fetch('https://www.ntzs.co.tz/api/v1/swap', {
method: 'POST',
headers: {
'Authorization': 'Bearer ntzs_live_xxxxxxxxxxxx',
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(), // recommended: one key, one swap, ever
},
body: JSON.stringify({
userId: user.id,
fromToken: 'USDT', // 'NTZS' | 'USDC' | 'USDT'
toToken: 'NTZS',
amount: 100,
minOutput: rate.minOutput, // recommended: the floor from your quote
slippageBps: 100, // optional, default 100 (1%); max 500
}),
})
const reader = res.body!.getReader()
const decoder = new TextDecoder()
while (true) {
const { done, value } = await reader.read()
if (done) break
for (const line of decoder.decode(value).split('\n')) {
if (!line.startsWith('data: ')) continue
const event = JSON.parse(line.slice(6))
// CHECKING → balance check
// SENDING → user → solver transfer (txHash)
// FILLING → solver → user transfer (txHash)
// FILLED → complete (txHash)
// FAILED → event.error for code
if (event.status === 'FILLED' || event.status === 'FAILED') break
}
}POST /api/v1/swap: cross-chain (USDT BNB → nTZS Base)
body: JSON.stringify({
userId: user.id,
fromToken: 'USDT',
toToken: 'NTZS',
fromChain: 'bnb', // USDT sent from BNB Smart Chain
toChain: 'base', // nTZS received on Base
amount: 50,
slippageBps: 150,
})curl (raw SSE)
curl -N -X POST https://www.ntzs.co.tz/api/v1/swap \
-H "Authorization: Bearer ntzs_live_xxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"userId":"uuid...","fromToken":"USDT","toToken":"NTZS","amount":100}'
# data: {"status":"CHECKING","message":"Checking balance..."}
# data: {"status":"SENDING","message":"Sending 100 USDT to liquidity pool...","txHash":"0x..."}
# data: {"status":"FILLING","message":"Sending nTZS to your wallet...","txHash":"0x..."}
# data: {"status":"FILLED","message":"Swap complete!","txHash":"0x..."}