Skip to content

API reference

Transfers

Move value between users and to external addresses.

post/api/v1/transfers

Move value between users or to an external address

Provide exactly one of toUserId or toAddress, never both. Synchronous: a 201 is a confirmed on-chain transfer. The platform fee, if any, is taken from the amount, so recipientAmount is what arrives.

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

  • fromUserIdstring (uuid)required
  • toUserIdstring (uuid)

    Another of your users.

  • toAddressstring

    An Ethereum address on Base.

  • amountnumberrequired

    In token units. Decimal places may not exceed the token's (18 for nTZS, 6 for USDC/USDT).

  • amountTzsnumber

    Legacy alias of amount, read only when amount is absent.

  • tokenstringdefault "NTZS"

    Case-insensitive.

    NTZSUSDCUSDT

  • metadataobject

Responses

  • 201Transfer executed.Show fields
    • idstring (uuid)
    • statusstring

      A 201 is always a confirmed on-chain transfer.

      completed

    • txHashstring | null
    • tokenstring

      ntzsusdcusdt

    • amountnumber

      Amount debited from the sender, in token units.

    • recipientAmountnumber

      Amount received, after the platform fee.

    • feeAmountnumber
    • feeTxHashstring | null
    • toAddressstring

      The destination address actually paid.

    • amountTzsinteger

      Legacy alias of amount, nTZS transfers only.

    • recipientAmountTzsinteger

      Legacy alias of recipientAmount, nTZS transfers only.

    • feeAmountTzsinteger

      Legacy alias of feeAmount, nTZS transfers only.

  • 400Invalid request.CodeError
  • 401Missing, empty, or invalid API key. No machine-readable code is returned.BareError
  • 403Forbidden: a missing capability, unapproved KYB, a source IP outside your allowlist, or a frozen wallet.CodeError
  • 404user_not_found: the sender or recipient is not one of your users (details.role says which).CodeError
  • 409The Idempotency-Key has already been used ("This Idempotency-Key has already been used. Use a new key for a new request."), or another request for the same source wallet is still in flight. Nothing was done. Read the earlier request back rather than resending.SentenceError
  • 429Rate limited. Respect Retry-After and back off exponentially.CodeError
  • 503A rail or dependency is unavailable. Nothing moved; retry with backoff.CodeError
Request
curl -X POST "https://www.ntzs.co.tz/api/v1/transfers" \
  -H "Authorization: Bearer $NTZS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "fromUserId": "14e17d04-ec7f-4d99-91a3-dfbaca19fba1",
  "toUserId": "2b7e4f1a-9c3d-4e8b-a6f5-0d1c2e3f4a5b",
  "amount": 10000,
  "token": "NTZS"
}'
Response · 201
{
  "id": "14e17d04-ec7f-4d99-91a3-dfbaca19fba1",
  "status": "completed",
  "txHash": "0x5b1c…e2a9",
  "token": "ntzs",
  "amount": 10000,
  "recipientAmount": 10000,
  "feeAmount": 10000,
  "feeTxHash": "0x5b1c…e2a9",
  "toAddress": "0x531B87EfdEBD19bfd05700DF6218d4786Cf2201C",
  "amountTzs": 10000,
  "recipientAmountTzs": 10000,
  "feeAmountTzs": 10000
}