API reference

Errors

Every error the API returns, what causes it and what to do.

Errors are returned as a non-2xx status with a JSON body:

Error
{ "error": "Expected nonce 1" }

Submitting transfers

StatusErrorCause and fix
400Addresses must be 0x… EVM addressesCheck from and to
400Sender and recipient are the sameSend to a different address
400Amount must be a positive USDT amount with up to 6 decimalsUse a decimal string such as "12.5"
400Fee must be 0.01 USDTSend "fee": "0.01" and sign Fee: 0.01 USDT
400Bad nonceNonce must be a non-negative integer
400Memo is limited to 140 charactersShorten the memo
400Send JSONThe body was not valid JSON
401Signature does not match the senderThe message you signed differs from what the network rebuilt. See Signing transfers.
402Insufficient USDT for amount and feeThe balance must cover amount plus 0.01
403This address is frozen under the issuer policyThe sender is frozen. See Issuer controls.
403The recipient address is frozenThe recipient cannot receive USD₮
409Expected nonce nRead the nonce again from /address and re-sign

Faucet

StatusErrorCause
400Use a 0x… addressThe address is not valid
403This address is frozenFrozen addresses cannot receive
429Test USDT can be requested once every 24 hours per addressWait, or use another address
429Please wait a minute between requestsRate limit per IP address
429Too many requests. Try again in a minute.A rate limit was hit; wait retry-after seconds

Reads

StatusErrorCause
404Block not foundThe height has not been sealed yet
404Transaction not foundUnknown hash, or the transfer was never accepted
404Height outside the logInclusion proof for a block that does not exist
400Bad rangeConsistency proof with from of 0 or above to
404Unknown endpointCheck the path
500AnyServer error. Retry with backoff.

Failed at sealing

A transfer can pass submission checks and still fail when it is sealed, if the state changed in between. It is then stored with "status": "failed" and one of these errors, and no fee is charged:

ErrorMeaning
Frozen addressOne side was frozen before sealing
Nonce n is stale, expected mAnother transfer from the sender was sealed first
Insufficient balanceAnother transfer spent the balance first