Seller Financing

​

Lifecycle

​

Collateral modes

​

Asset leg

​

Token-side setup

• Freeze mode. The token’s owner grants the freeze adapter the agent role with addAgent(adapter). Only the owner can grant it. The adapter then freezes, unfreezes and force-transfers exactly the listed amount.
• Custody mode. The token must admit the custody adapter as a holder. On a token with an ERC-3643 identity register, the token issuer’s KYC operator issues an ONCHAINID for the adapter carrying the claims the register requires, and an agent of the register registers the adapter under it. On a Trusset ID Register, a KYC provider of the register verifies the adapter. On a token with its own contract allow-list, the token’s compliance admin allow-lists the adapter. A token with neither an identity register nor an allow-list, and no transfer rule that refuses the adapter, needs no step.

​

Roles

​

Interest

• FIXED charges one annual rate on the outstanding principal. On a market where sellers set the rate (sellerSetsFixedRate: true), the seller names it in fixedRateBps, up to the market’s maxFixedRateBps. Otherwise the operator’s fixedRateBps applies.
• DERIVED charges the operator’s base rate (baseRateBps) on the outstanding principal, plus a walk-away premium. The premium pays the seller for the buyer’s right to walk away from the sale. It is priced from the listing’s price and downpayment and from the operator’s volatility input (volatilityBps), and stamped on the listing as premiumA and premiumB. It accrues with the time since purchase, fastest at the start, and does not fall as principal is repaid.

​

Due dates, grace and default

​

Coverage rule

​

Fees

• Trusset interest share. 20 percent, rounded down, of every interest amount the seller receives, and of what the seller takes at liquidation. The rest is credited to the seller. The share is fixed in the market contract.
• Repay fee. Every repayment carries a fee, borne by the payer. It is carved out of the payment: the market keeps the smaller of the market’s repay fee and 0.5 percent of the amount applied, and only the rest goes to interest and principal. The factory stamps the repay fee on the market at deployment, in the payment token’s smallest unit: its default of 1.5 whole units of the payment token, for example 1.5 USDC, or a figure set for that payment token, at most 10 whole units. The market has no setter, so the fee never changes. Get Market returns it as repayFee and repayFeeFormatted, and Build Deployment in deployment.repayFee before you sign.

​

What each party receives

​

Base Path

https://api.trusset.org/seller-financing/api/markets

​

Which markets your instance reaches

• The deploying instance, which recorded the market with Record Deployment. Its rows carry access: { "kind": "DEPLOYER" }.
• A role holder. Any instance one of whose verified wallets holds OPERATOR_ROLE or DEFAULT_ADMIN_ROLE on the market. The role is read on chain with hasRole on every request that names the market, so a role the admin revokes closes the access at once. Its answers carry access: { "kind": "ROLE_HOLDER", "wallets": [...] }, naming the wallets and the roles they hold. List Markets lists such a market only when the wallet is the admin or operator named at deployment. A wallet granted a role later reaches the market by its ID on every route.

​

Response envelope

{
  "success": true,
  "data": { },
  "error": null,
  "metadata": {
    "timestamp": "2026-10-19T09:12:04.318Z",
    "requestId": "3f7c2a91-6d84-4b0e-9a15-c2e8f4d7b603",
    "instanceId": "inst_abc123"
  }
}

​

Writes

{
  "action": "SIGN_TRANSACTIONS",
  "chainId": 11155111,
  "steps": [
    {
      "to": "0x98aD0ca091552e23C564B41C74282e5343D03E8a",
      "data": "0x095ea7b3...",
      "value": "0",
      "functionName": "approve",
      "label": "Approve exactly the downpayment of 2000.0",
      "description": "Approve exactly the downpayment of 2000.0",
      "chainId": 11155111
    },
    {
      "to": "0xc35e5f74eC4C1dfB8cE2b8798D6161B706F9B5E1",
      "data": "0xefef39a1...",
      "value": "0",
      "functionName": "purchase",
      "label": "Buy listing 4 with a downpayment of 2000.0",
      "description": "Buy listing 4 with a downpayment of 2000.0",
      "gasLimit": "579315",
      "chainId": 11155111
    }
  ],
  "confirmStepIndex": 1,
  "preflight": {
    "simulated": true,
    "basis": "approvals-applied",
    "gasEstimate": "386210",
    "note": "Simulated with the approvals above applied first."
  }
}

• from names the signer. It is required on every write except Build Token Setup. Without it the answer is 400 FROM_REQUIRED, whose message names who signs that transaction, for example “Pass from, the wallet that signs this transaction: the buyer wallet that pays the downpayment. It is needed to check balances and roles and to simulate the transaction before you sign.”, with details: [{ field: "from", message }]. Build Deployment answers the same code with its own message and no details, after the MARKET_EXISTS check. The API reads that wallet’s balance and allowance and simulates the main transaction from it. When the contract would revert, the answer is 409 TX_WOULD_REVERT and nothing is built. Sign with the wallet you named, because no other wallet was checked.
• A wrong signer is named. On the operator builds (Update Configuration, Set Identity Register, Pause Market, Unpause Market) the answer carries signer: { role: "OPERATOR_ROLE", holders, holdersComplete }: the wallets that hold the role now, and whether the market’s role history was read in full. Cancel Listing and Liquidate carry signer: { role: "SELLER_OR_OPERATOR_ROLE", seller }. When from is not one of them, the TX_WOULD_REVERT refusal (AccessControlUnauthorizedAccount, NotSeller, or NotBuyer on Claim Asset) names the role in details.requiredRole and its current holders in details.roleHolders, and the message says which wallet to sign from.
• Approvals are exact. An approval step approves exactly the amount the market or the adapter pulls, never an unlimited amount. The one exception is a full payoff, which approves the payoff plus a margin, as below. When the wallet holds a smaller non-zero allowance, a step that resets it to zero comes first. When the allowance already covers the amount, no approval step is returned.
• A closing repayment ends with approve(0). The payoff approval carries a margin for interest that accrues until the payment is mined. The last step resets what is left of it. It is returned only when the response also approved.
• confirmStepIndex is the index of the main transaction: after any approval, before a trailing reset. That transaction carries the action. Watch its hash. Deployment is the only write with a confirm endpoint, so for every other write the result is read back once that transaction is mined.
• Gas headroom. When the main transaction simulates on its own, preflight reads { "simulated": true, "gasEstimate": "..." } and the main step carries gasLimit, the estimate plus 30 percent. When an approval comes first, the main transaction usually cannot be estimated on its own, because that approval is not mined yet. The API then simulates the approvals and the main call together, in order, from from (eth_simulateV1):
  • The bundle passes. The main step carries gasLimit, the gas the bundle used plus 50 percent, and preflight reads { "simulated": true, "basis": "approvals-applied", "gasEstimate", "note" }, as in the example above.
  • The main call reverts in the bundle. The build is refused with 409 TX_WOULD_REVERT and the decoded refusal, as for a single call.
  • The bundle cannot be simulated, for example on a node without eth_simulateV1. The response carries preflight.simulated: false with a note, and the main step has no gasLimit. The market’s own checks before the token transfer passed. Estimate the gas once the approval is mined.

​

Units

​

State is read from the chain

​

Deployment

1. Read Get Deployment Options for the factory, the modes, the default configuration, the bounds and the payment tokens of your network.
2. Build the deployment with Build Deployment. from must be a verified wallet of your instance. Any other wallet answers 403 DEPLOYMENT_NOT_INSTANCE_BOUND before any calldata exists. The API checks both tokens, the market identity register when you name one (it must have code, must not be either token or the retired Trusset ID Register, and must answer isVerified(address)), the asset’s freeze surface in freeze mode and the payment token’s decimals, then simulates the deployment from from.
3. Sign and broadcast the single deployMarket step from that wallet.
4. Record it with Record Deployment and the transaction hash. The API verifies the receipt against the factory and requires the signer to be a verified wallet of your instance. A deployment sent through a Safe, an EIP-7702 account or an ERC-4337 smart account is accepted: the API reads the wrapped call and takes the MarketDeployed event of the signing wallet. The answer carries the market record, the role assignment record and the token-side setup.
5. Complete the token-side setup with Build Token Setup, signed on the token issuer’s side.
6. Keep the role assignment record. Get Role Audit rebuilds it from the deployment receipt, checks each role live, and lists today’s role holders and every role, register and implementation change since. Get Role Certificate renders it as a PDF certificate under the same docRef, on the API key and in the Issuer Portal.

​

Walkthrough

1. Issuer. Get Deployment Options, then Build Deployment. Sign the step, then Record Deployment with its hash.
2. Token owner or register agent. Build Token Setup. Sign the step it returns.
3. Seller. Get Quote to size the terms, then Create Listing. Sign the steps, then read the listing ID from the ListingCreated event.
4. Buyer. List Listings with status=OPEN and Get Listing, then Purchase. Sign the approval and the purchase. The listing reads ACTIVE.
5. Buyer, each period. Get Loan Status for nextDue. Once the due date has passed and before its grace period ends, Repay the interest due plus the repay fee.
6. Buyer, at the end. Repay with amount: "full". Sign the approval, the repayment and the reset. The listing reads REPAID.
7. Buyer. Claim Asset. The listing reads COMPLETED.
8. Seller. Get Claimable, then Withdraw. The seller can withdraw its interest credits at any time during the loan as well.

1. Buyer. Misses a due date. After liquidatableAt, Get Loan Status reads isLiquidatable: true.
2. Seller or operator. Liquidate. The listing reads LIQUIDATED and the asset is back with the seller. On a custody market whose token refuses that return, the adapter holds it in escrow for the seller, and the seller takes it back later with Claim Escrowed Collateral.
3. Seller and buyer. Each reads Get Claimable and calls Withdraw: the seller for its compensation and interest, the buyer for its refund.

​

Pausing

​

Errors

{
  "success": false,
  "data": null,
  "error": {
    "code": "TX_WOULD_REVERT",
    "message": "The wallet is not verified on the market identity register.",
    "details": {
      "action": "listing creation",
      "error": "IdentityNotVerified",
      "args": [],
      "revertData": "0x7a61965e"
    }
  },
  "metadata": {
    "timestamp": "2026-10-19T09:12:04.318Z",
    "requestId": "3f7c2a91-6d84-4b0e-9a15-c2e8f4d7b603",
    "instanceId": "inst_abc123"
  }
}

​

Rate limits

​

Trust boundaries

• The token issuer keeps its powers over the asset. In freeze mode another agent of the token can unfreeze or force-transfer the frozen amount, and a recovery of the seller’s wallet by the issuer strands the lock. The market refuses a seller that is an agent of the token, but cannot refuse an agent role granted after the purchase. In custody mode an agent can force-transfer tokens out of the adapter, and the delivery then reverts. The issuer can also refuse every recipient or revoke the freeze adapter’s agent role.
• Refunds wait for the asset. Cancellation and liquidation return the asset before any money settles. While the freeze adapter lacks its agent role, or the custody adapter holds less than it recorded, they revert and the escrow waits until the token issuer restores the role or the holdings. A custody return the token merely refuses does not block them: the adapter keeps the asset in escrow for the seller.
• Delivery waits for the asset. A payoff credits the seller the full price, while the delivery to the buyer can revert once the asset left the seller’s wallet or the adapter. The API refuses the payoff and the claim while it reads that state (Asset leg), but it cannot stop an agent of the token from moving the asset after the payoff is mined.
• The payment-token issuer can block repayments. A paused stablecoin, or one that starts charging a transfer fee, makes every repayment revert, while liquidation, which moves no payment tokens, stays open. The operator’s only defence is pausing the market, which also stops liquidation.
• The admin can upgrade the market. An upgraded implementation is not bound by these rules. Compare the market’s ERC-1967 implementation slot with marketImplementation() on the factory.
• Configuration and screening apply to new business. A configuration change mined just before a pending listing applies to it, so check the terms stamped on the listing and cancel one you do not accept. A purchase re-checks that the seller holds no agent role on the asset token, but not that the seller is still verified on the market identity register, and anyone can repay a loan. The operator cancels the open listings of a seller who loses verification. A register change through Set Identity Register reaches new listings and purchases only.