Collateral token standards
The market itself is standard-agnostic. It tracks references and amounts and never touches the token, which is the collateral adapter’s job. What a market accepts is therefore decided by the adapter its collateral mode uses. ACUSTODY market holds collateral through the ERC-20 interface and nothing else. ERC-20, ERC-1400 and ERC-3643 all work there, and so does a token with custom compliance that happens to present an ERC-20 surface. A token that does not answer balanceOf and decimals is refused with COLLATERAL_TOKEN_NOT_ERC20. Rebasing tokens and ERC-1400 partitions are not supported.
A FREEZE market is the narrow one. Freezing a balance where it sits needs the ERC-3643 agent surface: getFrozenTokens, freezePartialTokens, unfreezePartialTokens and forcedTransfer. The API refuses the deployment with FREEZE_MODE_UNSUPPORTED_TOKEN unless both isAgent and getFrozenTokens answer, and refuses an ERC-7943 token that is not ERC-3643: its setFrozenTokens overwrites an absolute amount and comes with no agent role, so the freeze adapter can never act on it. CUSTODY is the answer for such a token.
Whatever the mode, the token must be imported into your instance with a published profile. The deployment attests the asset data built from that profile, so a token without one is refused with TOKEN_PROFILE_REQUIRED. See Deploy Market for the full list of refusals.
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. Routes keyed by a market ID refuse a market belonging to another instance with MARKET_NOT_FOUND. The market ID is your instance’s record ID for the market, as List Markets returns it, not the contract address. A contract address sent in its place answers MARKET_NOT_FOUND naming the record ID when your instance holds that market. See Market IDs.
Routes keyed by a market contract address work differently: the queue and adoption routes, the asset data routes, and Pledges. They first prove the address against the current lending factory and refuse any other with MARKET_NOT_V2, including a market deployed through an earlier factory generation. Each then applies its own per-market access rule.
A network the lending factory is not deployed on answers 503 SECURITY_LENDING_V2_NOT_CONFIGURED.
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. Two exceptions answer with a single message and no details: the asset data routes and Upgrade Market. Always branch on success rather than on the HTTP status alone.
A request refused before it reaches a route answers without data and instanceId. That covers an invalid key, a service not enabled on the instance, an exhausted credit allowance, a rate limit, and key material in the body.
Writes
Every write that changes chain state returns unsigned transaction data for a wallet you control to sign and broadcast. Nothing is submitted on your behalf.chainId your instance resolves to and value: "0", so a payload is bound to one network. Two exceptions carry their own value: Fund Bot sends the network’s native coin, and a contract creation has no to and is not stamped. Where a response also carries to and data at its top level, the stamp sits there, beside them. Each page shows where its fields sit.
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. Two operations return a signature request instead of a transaction, as SIGN_TYPED_DATA: Sign Price and Get Permit Quote.
A few writes change nothing on-chain and return their result directly. They save or unpublish terms of use, record a price attestation, configure hooks, update a bot’s record, and rename, repurpose, archive or rescan a whitelist.
Once you have broadcast a transaction, most endpoints confirm it when you call them again with its hash in the body:
confirmWith object. Confirm Lender Role, Confirm Configuration and Confirm Extension Transaction work that way. The asset data, whitelist and bot confirms do too. Set Vault Liquidity and Register Vault have no confirm call on this API.
The API verifies the mined receipt, records the result against the market, and returns the values that only exist after execution, such as loanId, positionId, liquidationId, and auctionId. Verification checks that the transaction succeeded, targeted the contract this endpoint operates on, and called the expected function on the entity you named. Some confirm calls also accept a transaction sent through a smart account or another contract, proven by the target contract’s own event, and mark it with verifiedBy: "receipt-log". See Confirming a Transaction.
No endpoint signs on your behalf, and Trusset never asks for, holds or uses a private key of yours. 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. The check reaches six levels deep and ignores case. The refused names are privateKey, private_key, mnemonic, seedPhrase, seed_phrase, keystore, keystoreJson, signerKey, signer_key, secretKey, secret_key, walletPassword, useRelayer, signOnBehalf, onBehalfOf and autoSubmit.
Collateral modes
Every market is deployed in one of two modes, fixed at deployment. Your instance can run one active market per collateral token, collateral mode and settlement asset. A second request for the same combination is refused withMARKET_EXISTS.
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.
CUSTODY escrows the tokens in the adapter. Borrowers must call approve on the collateral token for the adapter before posting collateral, and the API returns that approval as an explicit step. When the token gates holders, the adapter must be allow-listed on it or verified on its identity registry. A token that gates nothing needs no token-side step. If a return transfer is ever blocked by compliance, the borrower reclaims through Claim Escrowed Collateral.
A liquidation delivers seized tokens to the market’s liquidation router, or to its auction venue while Dutch auctions are on. Every recipient the token gates must be admitted on it: the router, the auction venue when auctions are on, and the sale recipient the router later delivers to.
Identity gates
A market examines two optional registers, both read as the first word ofisVerified(address). ERC-3643 identity registries, ONCHAINID-based registers and the Trusset register are all admitted.
The borrower register examines every loan the market opens and every further draw on it. With none installed, the collateral token’s own compliance alone governs who may borrow. A MARKET-priced market must carry one by the time it is adopted. The provider register is read by the vaults that fund the market, before each admits a depositor. The market itself takes direct deposits only from the operator wallet and registered vaults, and consults no register for them.
The market admin replaces or clears either register with Set Identity Gates. Read the current pair with Get Identity Gates.
Either register can also be a whitelist: a list that admits exactly the wallets its owner and managers listed, and examines no identity. A whitelist cannot be the borrower register of a MARKET-priced market. As a provider register it is accepted only when your instance owns or manages it, and only with your attestation, sent as attestIdentifiedMembers: true, that it lists identified wallets only. See Whitelists as Gates.
Either register can be the eligibility register of one of your verification profiles, named by its key instead of an address at deployment, at adoption and through Set Identity Gates. A gate built on a profile admits exactly the wallets admitted under it. A MARKET-priced market’s borrower register must qualify as a professional gate: every verification profile that admits wallets to it, on any instance of the market’s network and environment, is limited to professional clients and in the REGISTER mode, and there is at least one. Until it qualifies, the API opens no loan and adds no liquidity on the market. See Professional borrowers.
A vault funds a market only when the vault’s own register and the market’s provider register fit together. The market must name the vault’s register or no provider register at all. A vault without a register of its own adopts the provider register of the first market it funds and keeps it for good, so every later market must name that same register. See Vaults.
On Sepolia the previous Trusset ID Register, 0xE9114c40934f6fB6BB317935156b731f7A86D006, takes no new identities. A gate that still reads it admits only wallets verified before the register moved. Deploy Market, Set Identity Gates and Accept Lender Role refuse to install it with 422 IDENTITY_REGISTRY_RETIRED. Market reads flag it with retired: true and currentRegistry, and vault reads with depositorRegisterRetired: true and currentRegistry. A wallet such a gate does not admit is refused with 409 IDENTITY_GATE_RETIRED. See The previous Trusset ID Register.
Pricing
Prices come from one of four sources, fixed at deployment aspriceSource.
NAV is the default: a net asset value the market’s price signer publishes. MARKET is an observable market price the price signer attests. On a MARKET market the contract refuses Dutch auctions and holds the auction floor premium at 98 percent or more. The lender of record may declare EXCHANGE_SALE or ISSUER_REDEMPTION as its realization mode there, never AUCTION. The API also requires a borrower register, installed at deployment or brought by the nominated lender of record at adoption, and that register must qualify as a professional gate.
The price signer is the wallet the lender of record declared when it took the role. A NAV or MARKET market opens with the initialPrice stated at deployment. Sync Oracle Price returns the transaction that pushes a new price. Sign Price returns the EIP-712 payload for a price update, which the signer signs in its 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 positive price.
A signer that keeps its key outside your instance posts what it signed to Record Price Attestation. A later push of exactly that price then carries the attestation, and any wallet may broadcast it. Get Oracle Status reports whether the declared price signer is authorized, Verify Signer whether your instance’s own wallet is, and Get Oracle History lists what was attested and pushed.
ORACLE works the other way. The market reads an external feed named at deployment, and no opening price is stated. The deployment is refused when that feed cannot answer a positive price dated within 24 hours. Nothing is pushed to an ORACLE market: every price surface refuses it with EXTERNAL_FEED_ACTIVE.
FIXED holds the initialPrice stated at deployment for the life of the market, per whole collateral token in the settlement token (stablecoin). It is offered when the factory creates oracles that can hold a fixed price, and only where the token’s currency is the settlement token’s currency. A fixed price never goes stale. Its oracle refuses every signed price, so Sign Price and a signedPrice on any write answer FIXED_PRICE_ACTIVE. The price authority can only mark it down through Sync Oracle Price, within the deviation bound, which the Issuer Portal only tightens. A fixed price is not a market price, so the free-hand exchange sale is not available as the realization path. See Fixed price.
On every source but FIXED the oracle’s maxPriceAge decides when a price is stale, 24 hours by default. A stale price blocks opening loans, drawing more, withdrawing collateral against open debt and liquidating. Repayment never waits on a price.
Rate modes
The rate mode is chosen at deployment and read fromrateMode on List Markets, Get Market Metrics and Get Rate Mode.
Every rate is bounded at 500 percent. A
FIXED market must run loan terms with a duration, because the term clock replaces the rate curve as the pull toward repayment. Borrow More is refused on a fixed-rate loan: a new draw is a new loan at current terms.
After adoption the interest model owner, the issuer the lender of record named, can change the mode with Set Rate Mode. Accrual is settled under the old mode first. A new mode reaches every open variable-rate loan from then on, while a stamped fixed rate stays with the loan it was stamped on. Set Max Fixed Rate tightens the ceiling on future fixed rates and can only move it down.
On a FIXED market, borrowRate is the stamp a loan opened now would receive, the same figure as fixedStampRateBps. The utilization curve that still prices any variable loans is curveBorrowRate. What an outstanding loan pays was stamped when it opened, and Get Loan shows it. Quote a borrower from the offering block on Open Loan, which carries the rate, due date, grace and term penalty for the loan being opened.
Interest and fees
Repaid interest splits in a fixed order. Trusset takes its 15 percent infrastructure fee first. The operator share, 8 percent of the remainder, and the distributor share, 5 percent of it, come next. Both are fixed constants that nobody can change. The market’sprotocolFeeRate, which is its insurance-fund rate and zero by default, then applies to what is left. Liquidity providers receive the rest: 73.95 percent of repaid interest at the defaults.
The supply rate follows the same split. The operator share goes to the operator wallet. The distributor share goes to whoever provides the pool’s liquidity. A vault passes it to the distributors behind its depositors, and the operator’s own liquidity earns it for the operator. Get Fee Split reads the live split from the market.
A market can also charge a flat opening fee and a flat repayment fee. Both are stamped at deployment from defaults Trusset’s factory owner sets, both are zero unless set, and neither can change on the market afterwards. Each charge is capped at 0.5 percent of the amount. The borrower receives the borrowed amount less the opening fee and owes the full amount. A loan closes for its debt plus the smaller of the repayment fee and 0.5 percent of that debt. Liquidation and realization never charge either fee.
Every fee leg is booked on the market as a liability and leaves through a sweep to a fixed destination that nobody can redirect. Most sweeps may be sent by any wallet. See Sweep Operator Fees, Sweep Distributor Fees, Sweep Protocol Fees and Sweep Infrastructure Fees. Booked fees are never lent out and no liquidity provider can withdraw them.
Loan terms
A market can carry a term offering.maxLoanDuration sets how long a loan may run, and terminalDueDate sets a hard date every loan falls due by whatever its own duration. termGracePeriod sets how long after the due date an unpaid loan becomes realizable, 3 days by default. A market whose maxLoanDuration and terminalDueDate are both zero makes open-ended loans and none of this applies to it.
The offering is set at deployment and changed afterwards by the issuer with Set Term Config, which also sets the term penalty. On current markets each loan is stamped at signing with its due date, grace and term penalty, so a change reaches new loans only. Loans can be extended but never shortened: the issuer proposes and the market admin confirms, with Propose Extension once Set Allow Extension has switched the machinery on.
Terms change what liquidation means. A termed loan becomes realizable once its term runs past the due date plus grace, whatever its health factor. That is a second trigger alongside the health one. Get Liquidatable Loans reports both, naming the trigger on each loan.
Terms also bound the exit. latestDueAt and exitHorizon on Get Market Metrics and Get Exit Liquidity say when the book could in principle be wound down. An unbounded horizon means at least one open-ended loan is outstanding.
Liquidity
The operator wallet is the wallet that took the lender-of-record role. Apart from the vaults the market admin registered, it is the only address that may deposit into the pool directly with Add Liquidity, and it receives the operator share. It moves only by its own signature, with Rotate Operator Wallet. Every other liquidity provider deposits into one of the operator’s vaults. A vault reaches a market in two ways: the operator allocates vault funds to it, or the market draws on the vault at the moment a borrow needs the liquidity. The second needs consent on both sides. The market admin switches it on with Set Vault Liquidity and registers the vault with Register Vault. The vault operator sets a cap for that market in the Issuer Portal. A borrow above the pool’s free liquidity then draws what the shortfall needs from the registered vaults, in registration order, each within its cap.reserveRatio is the share of the pool held back from borrowing, set by the issuer with Set Reserve Ratio and capped at 50 percent. It never holds back a withdrawal. The figure that decides whether the pool alone can fund a loan is borrowableLiquidity, not availableLiquidity. It nets off the reserve and does not include what a vault could lend. Get Vault Liquidity shows each vault’s room.
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, and error.details names the field with Amount must be a number with at most N decimal places. A few responses also carry base-unit figures, most with a Raw suffix, and each page names them.
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. It reads null for a closed loan and for an open loan with no debt.
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. Until one institution takes the role, the market is seeking a lender of record. Its oracle, rate model and insurance fund belong to the market contract itself, which exposes no path to their settings, and its oracle has no price signer. Every administrative transaction on it would revert, and so wouldopenLoan and addLiquidity.
The deployer nominates candidates at deployment or later with Nominate Candidate, and withdraws a nomination with Withdraw Nomination. A market deployed with openToAnyCurator can also be claimed by an institution nobody nominated. Such a claimant must be verified on the borrower register the deployer installed, and the claim takes two transactions, announced and then completed after a delay. Without such a register only a nominee can take the market.
The API refuses the calls that would revert before a wallet signs rather than letting them be paid for in gas. Opening a loan, borrowing more and providing liquidity return 409 MARKET_PENDING_CURATOR while the market is in this state. So does every configuration call its admin or issuer would sign: risk parameters, rate mode, terms and extensions, reserve ratio, identity gates, vault liquidity, the auction venue, roles and upgrades. The token-side authorizations are still offered. Get Configuration Status reports the state 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, and a realizationMode of EXCHANGE_SALE, ISSUER_REDEMPTION or AUCTION. It may add a liquidityCommitment, identity registers, a liquidator, a vault, a fixed-rate ceiling, and the hash of the asset data it reviewed. The wallet that signs the adoption becomes the market’s operator wallet.
The role is taken through this API with Accept Lender Role, which returns the adoption transaction, and Confirm Lender Role, which records it. Because that binds an institution to another party’s market, this API admits only an institution Trusset approved as a lender of record, and refuses any other with CURATOR_NOT_APPROVED. List Queued Markets, Get Queued Market, Get Nominations and List Pending Markets show what is on offer. Get Operator shows who holds the role once taken. Operators walks through taking the role from start to finish.
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. The same transaction attests the asset data built from the token’s published profile and nominates the candidates who may become the lender of record.
2
Adopt
A candidate takes the lender-of-record role with Accept Lender Role and Confirm Lender Role. Taking it names the market’s parties and declares how seized collateral is realized. On a market from an earlier factory generation, the named owners then accept the oracle, rate model and insurance fund. See Get Handover.
3
Authorize
A new market cannot take loans until the token-side authorizations are complete. Get Setup Steps and Get Configuration Status list the outstanding items. Configure Market returns the calldata for each. The token-side items 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, the insurance-fund rate, caps, and auction behaviour. Defaults are seeded at deployment. Dutch auctions also need an auction venue, wired with Wire Auction Module.
5
Publish terms
The lender of record publishes its terms of use with Save Terms. A loan opened on a market without them is not refused, but its calldata carries a warning.
6
Price
A
NAV or MARKET market opens with its deployment price. Push a fresh one with Sync Oracle Price once the price signer exists and before the last price turns stale. Loans revert against a stale price.7
Fund
The operator wallet deposits the borrow asset with Add Liquidity, and registered vaults fund the rest. The first deposit into an empty pool must be at least 1,000 whole units of the borrow asset.
8
Lend
Borrowers open positions with Open Loan.
Liquidations
A loan becomes liquidatable when its health factor falls below1.0, or when a termed loan runs past its due date plus grace. A term realization takes the whole debt at the term penalty and releases the collateral it does not need back to the borrower. Liquidation needs LIQUIDATOR_ROLE on the market, which Set Liquidator Role grants and a connected liquidation bot can hold. What happens next depends on the market’s useDutchAuction setting.
With Dutch auctions enabled, seized collateral moves to the market’s own auction venue, which must be wired first with Wire Auction Module. The auction’s price decays linearly from auctionStartPremium to auctionMinPremium of the liquidation price over auctionDuration. Bidders buy collateral from the venue through Bid on Auction, and the borrower may not bid. Collateral unsold when the auction expires routes to the liquidation router through Settle Expired Auction, which anyone may call unless the market is paused.
With Dutch auctions disabled, seized collateral transfers straight to the liquidation router and a pending liquidation is recorded.
Once collateral reaches a router in two-step mode, where every router starts, it does not sell itself. There is no auto-sell for external securities. The only on-platform venue is the market’s own auction venue. It sells only what a liquidation seizes into it while its auction runs, and nothing moves from the router back into an auction. 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. It must pass the token’s compliance checks. The operator decides when and how much, never where. The router admin can rotate the destination only through an announced, one-hour-delayed proposal that is refused while any realization is in flight. This API does not expose that rotation.
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. It is refused while collateral of the record still sits on the router.
EXCHANGE_SALE can run its router in atomic mode instead. A liquidation there sells the seized collateral to the sale recipient at its standing bid inside the liquidation transaction and settles the record at once. A liquidation the sale recipient cannot pay reverts, and the loan stays liquidatable. Atomic mode is off on every router until its administrator switches it on with Set Atomic Mode. Get Atomic Sale reports the state, the sale recipient posts its bid with Set Sale Bid, and Sell Pending Liquidation sells a record already on the router.
The market keeps at most the position’s debt at seizure plus the penalty: the liquidation penalty on a health liquidation, the loan’s term penalty on a term realization. Proceeds above that are returned to the borrower by the contract. If the transfer to the borrower fails, the surplus is escrowed on the market for the borrower to claim with Claim Surplus, rather than reverting the settlement.
When a first settlement retains less than the record’s claim, the market draws on its insurance fund for the gap in the same transaction. Only the principal neither covers is the pool’s loss. The fund pays what its balance allows, and a fund that is empty or refuses the market covers nothing and blocks nothing. Get Insurance Status shows its balance and which rule a market runs.
A liquidation left unsettled for 7 days can be written off with Handle Liquidation Timeout, which draws on the insurance fund to cover the bad debt. Write-off does not recover collateral from the router, so dispose of or return the collateral first. Two router-admin calls finish the router’s side. Close Liquidation closes a router record once the market’s record is closed and nothing is left to sell. Reopen Liquidation reopens a settled record that collected nothing while collateral remains on the router.
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. The settlement endpoints check the router role against your instance’s primary verified wallet, so that wallet must hold OPERATOR_ROLE. Name it as liquidationOperator, or grant it the role with Set Access Role.
Every market payload carries liquidationRouterAddress. Endpoints that act on a liquidation resolve the correct router automatically.
Every market on the current factory carries its own router for its whole life. Deployment rejects a market without one and no setter can clear it, so there is no shared router to fall back to. Two consequences follow. A router read that fails is a retryable failure rather than a reason to guess, and it comes back as ROUTER_UNRESOLVED. And liquidation IDs restart at 1 on each router, so the same ID can name a different liquidation on two markets in one instance. The settlement endpoints take a marketId to say which you mean, and refuse with AMBIGUOUS_LIQUIDATION_ID when it is missing and needed.
Error codes
The endpoint pages list the codes each route returns, with the HTTP status and what to do. This table collects the codes of whitelists, fixed prices, pay-to addresses, the atomic sale, vault groups, the client of record and the previous Trusset ID Register, and names the pages that return them. A row marked Warning arrives in a successful answer as a{ code, message } entry of warnings and does not stop the call. The row marked Step code is an entry of accessListSteps. A row marked Issuer Portal is answered only by the Issuer Portal, never to an API key.
Rate limits
Every request made with an API key counts against a ceiling of 200 requests per minute for that key, on every product. Most endpoints on this surface also draw on one of two tighter budgets. Each budget is counted per API key across every endpoint that carries it, not per endpoint.
Reads not named above are bounded only by the 200 per minute ceiling.
Exceeding a limit returns
429 with code RATE_LIMIT_EXCEEDED and a Retry-After header in seconds. The 200 per minute ceiling reports its state on every response in X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. The two tighter budgets report theirs in RateLimit-Limit, RateLimit-Remaining and 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 metered 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.