Skip to content

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..."}