Base Path
Every request authenticates with an instance API key in the
X-API-Key header. See Authentication. The instance bound to your key determines both the network and the data you can reach. Markets belonging to another instance return MARKET_NOT_FOUND.
Response envelope
success is false, data is null, and error carries code and message. Schema failures use VALIDATION_ERROR with error.details listing each offending field. Always branch on success rather than on the HTTP status alone.
Writes
Every write endpoint returns unsigned transaction data for a wallet you control to sign and broadcast. Nothing is submitted on your behalf.transaction object carries the chainId your instance resolves to and value: "0", so a payload can never be broadcast against the wrong network by accident.
Some operations need more than one transaction. Those return SIGN_TRANSACTIONS with an ordered steps array that must be broadcast in sequence.
confirmStepIndex and confirmWith. Confirm with that step’s hash, which is not always the last one.
Once you have broadcast a transaction, call the same endpoint again with its hash in the body:
loanId, positionId, liquidationId, and auctionId. Verification checks that the transaction succeeded, targeted the market this endpoint operates on, and called the expected function on the entity you named. See Confirming a Transaction.
Trusset never holds, fetches or uses a private key, and no endpoint signs on your behalf. This is enforced rather than assumed. A write whose body carries a field named for key material, or for signing on behalf of someone else, is rejected with 400 KEY_MATERIAL_REJECTED at any nesting depth. The refused names include privateKey, mnemonic, seedPhrase, keystore, signerKey, secretKey, useRelayer, signOnBehalf, onBehalfOf and autoSubmit.
Collateral modes
Every market is deployed in one of two modes, fixed at deployment. A single collateral token can back several markets, as long as they differ in collateral mode or in settlement asset.FREEZE is the default. The adapter freezes the borrower’s tokens where they sit. The borrower keeps custody and no ERC-20 approval is needed to open a loan. This requires the market’s adapter to hold the agent role on the collateral token, granted by whoever controls that token’s agent administration. The token must implement the ERC-3643 freeze interface (isAgent and getFrozenTokens), which is checked at deployment and rejected with FREEZE_MODE_UNSUPPORTED_TOKEN if absent.
CUSTODY escrows the tokens in the adapter. Borrowers must call approve on the collateral token before posting collateral, and the API returns that approval as an explicit step. This requires the adapter to be a verified holder on the token’s identity registry. If a return transfer is ever blocked by compliance, the borrower reclaims through Claim Escrowed Collateral.
Both modes require the market’s liquidation router to be an eligible recipient of the collateral token, because a liquidation transfers seized tokens to it.
Pricing
There is no automatic price feed. Prices come from the issuer, as a net asset value the issuer publishes. Sync Oracle Price pushes a NAV on-chain. Sign Price returns the EIP-712 payload for a price update, which you sign in your own environment. A borrower then submits that signature alongside their own transaction, updating the price atomically without a separate oracle write. Both endpoints require an explicit positiveprice. Both also require the signing wallet to be an authorized signer on the market’s oracle.
priceSource records how the market’s price is meant to be interpreted. NAV is the default. MARKET signals an observable market price and the contract responds by disallowing Dutch auctions and raising the auction floor premium. The backend applies no branching of its own on this field.
Units
Three separate decimal domains apply. Send and receive plain decimal strings in every case. Do not send base units.
Both decimal values are on the market record from Get Market. Sending more decimal places than the target token supports returns
VALIDATION_ERROR with the message Amount must be a number with at most N decimal places.
Risk parameters are integers in basis points. 7500 is 75 percent. Health factor is a decimal string where 1.0 is the liquidation boundary: at or above is healthy, below is liquidatable.
The borrow asset is fixed at deployment. Any ERC-20 with 6 to 18 decimals is accepted, validated on-chain at deploy time. Omitting it selects USDC. See List Borrow Assets.
Lender of record
A market is deployed without parties. It names no admin, no issuer and no collateral agent. Instead it carries thecandidates you nominated at Deploy Market. Until one of them takes the role, the market is seeking a lender of record. DEFAULT_ADMIN_ROLE, ISSUER_ROLE and the oracle owner are all unheld, so every administrative transaction on it would revert. openLoan and addLiquidity revert too.
The API refuses those calls before a wallet signs rather than letting them be paid for in gas. Opening a loan, borrowing more, providing liquidity, changing risk parameters and changing who may liquidate all return 409 MARKET_PENDING_CURATOR while the market is in this state. Get Configuration Status reports it as pendingCurator, and never reports a market fully configured while it holds.
Taking the role is what names the parties. The adopting institution declares its own admin, issuer, collateralAgent, saleRecipient, liquidationOperator, oracleOwner and priceSigner, a realizationMode of EXCHANGE_SALE, ISSUER_REDEMPTION or AUCTION, and a liquidityCommitment. Because that binds an institution to another party’s market, the right to take the role is granted by Trusset and is not derived from a nomination alone.
Adoption is not performed with an instance API key. A nominated institution takes the role from its own Trusset issuer account. This surface exposes two reads. Get Nominations shows who has been nominated on a market. List Pending Markets shows the markets currently seeking a lender of record.
Market lifecycle
1
Deploy
Deploy Market deploys the market, oracle, interest model, insurance fund, collateral adapter, and a dedicated liquidation router, in one factory transaction. It also nominates the candidates who may become the lender of record.
2
Adopt
A nominated candidate takes the lender-of-record role, which names the market’s parties and declares how seized collateral is realized. Track it with Get Nominations.
3
Authorize
A new market cannot take loans until token-side authorizations are complete. Get Setup Steps returns the outstanding items with ready-to-sign calldata. These are executed by the token’s agent or identity registry operator, not by Trusset.
4
Configure
Update Market Config sets collateral factor, liquidation threshold, penalties, fees, caps, and auction behaviour. Defaults are seeded at deployment.
5
Price
Push an initial NAV with Sync Oracle Price. Loans revert against a stale price.
6
Fund
Liquidity providers deposit the borrow asset with Add Liquidity. The first deposit into an empty pool has a minimum.
7
Lend
Borrowers open positions with Open Loan.
Liquidations
A loan becomes liquidatable when its health factor falls below1.0. What happens next depends on the market’s useDutchAuction setting.
With Dutch auctions enabled, liquidation opens an auction whose price decays linearly from auctionStartPremium to auctionMinPremium over auctionDuration. Bidders buy collateral through Bid on Auction. Collateral unsold when the auction expires routes to the liquidation router through Settle Expired Auction.
With Dutch auctions disabled, seized collateral transfers straight to the liquidation router and a pending liquidation is recorded.
Once collateral reaches the router it does not sell itself. There is no auto-sell for external securities, because these instruments have no on-platform venue. The operator drives settlement explicitly:
1
Withdraw for sale
Withdraw Collateral for Sale moves collateral to the sale recipient the lender of record fixed when it took the role. That destination cannot be rotated, and it must pass the token’s compliance checks.
2
Sell off-platform
Execute the sale through your own channel. Trusset is not involved.
3
Report proceeds
Report Partial Sale deposits interim proceeds into the router. Repeatable.
4
Settle
Settle Liquidation routes the cumulative proceeds to the market and closes the liquidation.
Per-market liquidation router
Each market gets its ownSecurityLiquidationRouter, deployed by the factory in the same transaction. The market admin holds DEFAULT_ADMIN_ROLE on it and the liquidationOperator holds OPERATOR_ROLE. Both are named by the lender of record when it takes the role, not at deployment. Trusset holds no role. Naming your registered wallet as liquidationOperator is what allows settlement to be driven through this API.
Every market payload carries liquidationRouterAddress. Endpoints that act on a liquidation resolve the correct router automatically. Markets deployed before per-market routers existed continue to use the shared legacy router, transparently.
Rate limits
Every request made with an instance API key counts against a ceiling of 200 requests per minute for that key. Some endpoints carry a second, tighter limit on top of it:
Reads not named above are bounded only by the 200 per minute ceiling. Verify Signed Price is a write that carries no tighter limit, because it reads a signature rather than moving anything.
Exceeding a limit returns
429 with code RATE_LIMIT_EXCEEDED, a Retry-After header in seconds, and X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. See Rate Limits.
Credits
Requests on this surface also draw on your instance’s monthly API credit allowance, billed against the lending service. Every response carriesX-Credits-Limit, X-Credits-Remaining and X-Credits-Reset, plus an X-Request-Id you can quote in support requests. When the allowance is exhausted the request is refused with 402 and code CREDIT_LIMIT_EXCEEDED, and metadata carries creditsLimit, creditsRemaining and resetsAt. Credits consumed by a request that fails with a 5xx are refunded automatically.