Skip to main content
The Swap API, organization keys, and one set of conventions

New

  • Swap API. Discover networks and pairs, then quote, build, and relay swaps on Ethereum and Solana. Swap API
  • Redemption preparation. POST /v1/redemptions/prepare returns the redemption to send back, the typed data to sign, the $TSY approval it needs, and checks that show whether intake would accept it. Redeem at size
  • Organization keys and scopes. An admin can create keys that belong to the organization, each with the scopes it needs: read, trade, cp:operate, or cp:admin. Authentication
  • Testnets. evm-sepolia and svm-devnet run on the production host. Testnets
  • Solana asset decimals. Solana deployment info gives each asset’s decimals, as Ethereum deployment info does. Deployment info
  • Decode a transaction. POST /v1/swap/decode says what a transaction does, with its function or instructions, labels for the addresses Multiliquid lists, and a summary to show the user. Decode
  • Your organization. GET /v1/organization returns the organization a credential acts for, its id and name, for any API key of any scope or an account session with a selected organization. An account session that selects none gets 403 with the new code ORGANIZATION_NOT_SELECTED on every route it is sent to, public routes included. Delegates
  • Batch order capacity check. Batch order preparation returns checks.capacity, which compares what the order would reserve with the capacity the capital provider has left, on Ethereum and Solana. Checks
  • Delegate administration. GET /v1/organizations/{organizationId}/delegates/{delegateId}/admin/state reads a stablecoin delegate’s on-chain configuration, with optional whitelist, blacklist, and admin checks, for a key with read. POST /v1/organizations/{organizationId}/delegates/{delegateId}/admin/prepare returns the unsigned transaction for one admin action, such as whitelisting an RWA, setting a rate or custody address, or pausing, with checks of whether it would succeed, for a key with cp:admin. Your capital provider admin wallet signs and sends it. Administer your delegate
  • TOKEN_ACCOUNT_MISSING. A Solana batch order whose user lacks a token account for the pair answers this code, with the mint, the account, and its token program in details. Batch orders

Changed

  • Ethereum transactions are ready to sign. Every unsigned EVM transaction the API returns, a build’s approval and swap, a batch order’s or redemption’s approval, and a delegate admin transaction, carries the sender’s nonce, gas, maxFeePerGas, and maxPriorityFeePerGas, read from the chain, and serialized, the unsigned EIP-1559 bytes to sign. Sign it as returned, without setting a nonce or fees. An approval and a swap take consecutive nonces, and a swap that needs an approval is simulated after it, so it has its own gas. checks.simulation reports approvalRequired only when the swap can be simulated only after its approval lands, and the new approvalReverts when the approval itself would revert, with the approval’s revert as error. gas and serialized are null for a transaction that cannot succeed now. A transaction whose nonce was used since the build gets 409 NONCE_ALREADY_USED from POST /v1/submissions: build again. POST /v1/swap/decode rejects a serialized that does not match its transaction’s fields. Transactions on EVM
  • Amounts are whole tokens. Every token amount the API takes or returns is in whole tokens, as a decimal string such as "1500.25", in place of base units: quotes, builds, fees, checks, batch orders and capacity, redemptions, settlements, /v1/transactions, decoded effects, and error details. A request’s amount has at most 6 decimal places and no more than the token’s decimals, and is never a JSON number; a response’s is exact, and null where the token’s decimals are unknown. This breaks a client that sends base units: "1000000" USDC now means a million USDC, and a value with too many decimal places is rejected. What the user signs keeps base units: typed data, prepared batch order and redemption bodies, and transaction calldata, value, and gas. A submission’s inclusion.fee is whole ETH or SOL, each redemption check and shortfall error names its token, and percentages are whole basis points named …Bps. Amounts
  • One network vocabulary. Every route takes evm-mainnet, evm-sepolia, svm-mainnet, or svm-devnet. Network keys
  • Errors say what to do. Every error carries a code, a requestId, and details where there is more to say. Errors
  • One set of names. Fields are camelCase, and every resource you poll reports a state. Conventions
  • Batch orders move to /v1/batch-orders, with one flow on both chains: prepare, sign, and submit, with the Ethereum approval as a transaction to sign, and cancellations prepared and signed the same way. Reads look like a swap, with the states accepted, processing, completed, failed, canceled, and underReview. A batch’s ID is batchId, and pairs list the capital providers that take batch orders in batchCapitalProviders. The capital provider routes move under /v1/batch-orders/capital-providers. Place a batch order
  • Redemptions are prepare, sign, and submit: POST /v1/redemptions takes {redemption, signature}. Reads name amounts as a swap does, amountIn and amountOut, and report a state, a statusDetail, and a settlement. GET /v1/redemptions/config and GET /v1/redemptions/eligibility are removed, because preparation returns what they did. Redeem at size
  • A build names its transactions. POST /v1/swap/build, in place of POST /v1/swap/transaction, returns approval on Ethereum or accountCreation on Solana, each null when not needed, then swap, in place of steps. Each description gives its amounts, such as Swap 1 USDC for at least 0.9949005 WTGXX. Build response
  • Quotes give what the user confirms. A quote no longer carries route or observedAt, and each nav entry is its token, value, and currency. A build’s quote is the amounts, price, fees, and capital provider. Quote response
  • One submission request per build. POST /v1/submissions takes a build’s transactions together, as signedTransactions, and sends the swap once the approval or account creation before it is confirmed. A transaction waiting its turn is queued, and a failed submission’s error carries a code. Submissions
  • GET /v1/swap/tokens is removed. GET /v1/swap/pairs lists every token. Discovery
  • Rate limits rise to 300 requests a minute for each group of anonymous routes, and 600 a minute for requests with a credential. Rate limits
  • Quotes use only the listed capital providers. A quote or build considers only the capital providers whose delegates whitelist the pair, the ones GET /v1/swap/pairs lists, so a $TSY-to-USDC quote is filled by the Treasury capital provider alone, and answers NO_QUOTE above what Treasury custody can pay out. A named capitalProvider that the pair does not list answers UNSUPPORTED_PAIR. Discovery
  • $TSY quotes follow Treasury credits. With user, $TSY in above the user’s credits, none included, is rejected with InsufficientCredits. Without user, a $TSY quote is indicative, priced as a wallet with no accrued yield would be. $TSY that cannot be priced now is rejected with CreditsUnavailable, and any Ethereum quote that rounds to zero with ZeroAmount. Quote
  • $TSY mint eligibility. A build whose $TSY output the Treasury capital provider mints checks the receiver against the $TSY allowlist, and reports allowlisted or notAllowlisted. Eligibility
  • Approvals name their spender. An approval’s description names the delegate as decode labels it, such as Approve 1 USDC to the USDC delegate of capital provider Uniform Labs. Build response
  • Quotes and builds are not cached. Both answer with Cache-Control: no-store. Quote
  • Redemption preparation reports failing checks. POST /v1/redemptions/prepare answers 200 when the depositor’s Treasury credits fall short, none included, with checks.credits failing, and prices the full amount at the depositor’s own rate. An amount too small to redeem is INVALID_BODY, and a quote that reverts is NO_QUOTE with details.providers. checks.liquidity.available and INSUFFICIENT_LIQUIDITY’s details.available are the most USDC Multiliquid can pay out now, whatever the redemption’s size, and checks.liquidity.sufficient is intake’s decision. Prepare and sign
  • Redemption intake order. Intake checks the form of every field, the signature’s included, before the operator, and UNSUPPORTED_ROUTE names its field. Lifecycle
  • Errors carry more details. Batch order preparation’s NO_QUOTE names the capital provider and the decoded error, as a swap quote’s does, UNSUPPORTED_FIELD gives the field and network, and the info routes name a rejected runtime or chain in details.field. Errors
  • Stricter requests, consistent addresses. Every route rejects an unknown query parameter with INVALID_REQUEST, and points a credential sent in the query string to the Authorization header. An INVALID_REQUEST or INVALID_BODY error gives details.field when one value is at fault, and details.location when its place is known. A rejected network name is followed by its canonical key, such as unsupported network `mainnet` (evm-mainnet). GET /v1/info and GET /v1/volume return addresses in lowercase hex, as every other route does. Conventions
  • List cursors. A cursor continues only the listing it was issued for: the same route, network, and filters, and for a private list the same organization. A cursor issued before this release is rejected; start the list again. Conventions
  • The OpenAPI document’s version. Its info.version is the release the API runs. Introduction

Deprecated

  • The flat redemption body. POST /v1/redemptions still accepts the earlier flat body, which SDK 0.5.x sends, but it is deprecated. Send {redemption, signature}. Redeem at size
  • The requestId and status redemption filters. GET /v1/redemptions still accepts them, because SDK 0.5.x sends them, but they are deprecated. Filter by redemptionId and state. Listing redemptions