API reference
Transfers
Move value between users and to external addresses.
/api/v1/transfersMove 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-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
fromUserIdstring (uuid)requiredtoUserIdstring (uuid)Another of your users.
toAddressstringAn Ethereum address on Base.
amountnumberrequiredIn token units. Decimal places may not exceed the token's (18 for nTZS, 6 for USDC/USDT).
amountTzsnumberLegacy alias of
amount, read only whenamountis absent.tokenstringdefault "NTZS"Case-insensitive.
NTZSUSDCUSDTmetadataobject
Responses
201Transfer executed.Show fieldsHide
idstring (uuid)statusstringA 201 is always a confirmed on-chain transfer.
completedtxHashstring | nulltokenstringntzsusdcusdtamountnumberAmount debited from the sender, in token units.
recipientAmountnumberAmount received, after the platform fee.
feeAmountnumberfeeTxHashstring | nulltoAddressstringThe destination address actually paid.
amountTzsintegerLegacy alias of
amount, nTZS transfers only.recipientAmountTzsintegerLegacy alias of
recipientAmount, nTZS transfers only.feeAmountTzsintegerLegacy 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
- 404
user_not_found: the sender or recipient is not one of your users (details.rolesays which).CodeError - 409The
Idempotency-Keyhas 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-Afterand back off exponentially.CodeError - 503A rail or dependency is unavailable. Nothing moved; retry with backoff.CodeError
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"
}'{
"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
}