state, or a repeated request on one route handles it on all of them. A field that departs from a convention is described on its route’s page.
Names
Amounts
Every token amount the API takes or returns is in whole tokens, as a decimal string:"1500.25" is 1,500.25 USDC. The API converts it with the token’s decimals, so you never scale an amount yourself.
- In a request, an amount has at most 6 decimal places, and no more than the token’s decimals. It is a JSON string, never a JSON number, with digits and at most one
.between them: no sign, exponent, separators, or spaces. Any other value is rejected withINVALID_BODY, orINVALID_REQUESTin a query string, anddetails.fieldnames it. - In a response, an amount is exact, up to the token’s decimals, without trailing zeros or an exponent, so an 18-decimal token such as $TSY can show 18 decimal places:
"995.210000000000000001". Store it as a string or a decimal type, not a floating-point number. - Unknown decimals. An amount whose token’s decimals Multiliquid cannot resolve is
null, never base units: a batch order’s amounts and its settlement legs’ when the network no longer lists the token (a submission’s settlement keeps the decimals it recorded, so its amounts arenullonly when the token cannot be resolved at all), a batch requirement’s totals when itstokenisnull, an amount in transaction history whose asset is not listed, and a decoded effect whose token is not listed, unless a SolanaTransferCheckedorApproveCheckedstates its decimals. - Errors. The amounts in an error’s
detailsand message, such asrequired,available,bound, andquoted, are whole tokens too. - Network fees. A submission’s
inclusion.feeis whole ETH on Ethereum and whole SOL on Solana. Gas stays in gas units, and gas prices in wei.
- EIP-712
typedData, and the prepared batch orderorderand redemptionredemptionthat you send back, including the body ofPOST /v1/redemptions; - a built or prepared transaction’s
data,value,gas, fees, andserializedbytes, and the arguments of a decoded call or instruction; - a capital provider’s released order payloads, which the operator executes.
signedTsyBound and actualUsdcOut, also keep base units. The interactive reference marks each one deprecated.
Shared objects
A response that describes one of these uses the same object on every route.
Each settlement also names its transaction:
In a submission’s or batch order’s settlement,
blockNumber and settledAt are null when not recorded, and a submission’s settledAt always is. A leg’s inputToken, outputToken, or fees is null when the token cannot be resolved, and so is its amountIn or amountOut in that token. A settlement token’s symbol, name, and kind are null for a token Multiliquid does not configure.
An object whose form depends on the network carries runtime, evm or svm, which names its form.
Absent values
A field that does not apply to a form of an object is omitted: a Solana submission has nononce, and a Solana build’s checks have no allowance. A field that applies but has no value, or none yet, is present and null: a token’s issuer, a capital provider’s name, a pending submission’s inclusion, and a redemption’s settlement before it completes. A field your credential may not read, such as a redemption’s receiver, is omitted.
Lists
A paginated list returnsnextCursor, null on the last page. Pass it back as cursor to the same route, with the same network and filters, and, for a list of your organization’s records, with a credential of the same organization. Another limit is fine. A cursor sent with anything else is a 400 with code INVALID_REQUEST, details.field cursor, and details.location query.
Address casing
An EVM address or hex ID in a response is lowercase0x hex, so one token, capital provider, or wallet reads the same on every route: in token and capital provider objects, in user, receiver, and operator, in check and error-detail values such as token, spender, and expected, and in a message that names an address. A request accepts an address in lowercase, in uppercase, or in EIP-55 mixed case, and a mixed-case address must carry a valid checksum.
EIP-712 typedData, and a prepared order or redemption that you sign and post back, keep the casing they are signed in. Solana addresses and signatures are base58.
Repeated requests
An identical repeat of a signed request answers2xx with the resource and replayed: true, and a first acceptance carries replayed: false. POST /v1/submissions sets replayed on each entry of submissions. POST /v1/redemptions answers this way too, except that repeating a failed redemption whose failure.resubmittable is true restarts it, with 200 and replayed: false.
Batch order intake is the exception. It never returns an existing order as a success, and answers 409 with code DUPLICATE_ORDER and the accepted order in details.orderId. Retries and idempotency covers each route.
One status per condition
- A conflict with current state is
409on every route.NONCE_ALREADY_USEDandPREPARED_ORDER_STALEalways are. - A signed operator that is not the one required is
OPERATOR_MISMATCH, a409whosedetails.expectedis the operator to sign for, ornullwhen there is none. - A shortfall reports
requiredandavailableindetails, in whole tokens, withtokenwhere a token is involved;INSUFFICIENT_CREDITSis always $TSY andINSUFFICIENT_LIQUIDITYalways USDC, and they name none. - A network that the API does not serve answers
503with codeNETWORK_NOT_ACTIVEanddetails.networkon a route that needs the network, such as a quote, a build, or a submit. Sending the request again cannot succeed. A route that only reads stored records, such as listing or reading submissions, answers for every known network. - An unknown network key is a validation error on every route, and a transient outage is
SERVICE_UNAVAILABLE. - An unknown query parameter is a
400with codeINVALID_REQUESTon every route in the OpenAPI document, a route that takes a JSON body included, so a misspelled filter or a credential in the query string is never ignored. - A rejected value is named: an
INVALID_REQUESTorINVALID_BODYerror givesdetails.fieldwhen one parameter or field is at fault, anddetails.location(query,path, orbody) when the place of the rejected value is known. A conflict between values, such ascreatedAfterat or aftercreatedBefore, gives only its location, and a rejection that cannot name the value at fault, such as a value the service cannot store, has nodetails.
Related
Errors
The error body and every error code.
Network keys
Network names and the networks each route serves.