> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trusset.org/llms.txt
> Use this file to discover all available pages before exploring further.
# API Introduction
> Unified REST API for the Trusset Protocol
The Trusset API provides programmatic access to tokenization infrastructure, custody operations, trading, lending, and the MiCA Register. All endpoints follow REST conventions and return JSON responses.
## Base URL
```
https://api.trusset.org
```
## Response Format
Every response follows a consistent envelope:
```json theme={null}
{
"success": true,
"data": { ... },
"metadata": {
"requestId": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2025-01-15T10:30:00.000Z"
}
}
```
Error responses include a machine-readable `code` and human-readable `message`:
```json theme={null}
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Search query too long (max 200 chars)"
}
}
```
## Available APIs
Customer lifecycle management, on-chain identity verification, transfer compliance checks, and KYC verification links. Customer records require the `customers` service; identity verification, verification profiles, and ID links require `identity`.
Query the EU MiCA registry. Search licensed CASPs, ART issuers, EMT issuers, and non-compliant entities sourced from ESMA. Free access with a MiCA API key.
Deploy, issue, redeem, and manage ERC-3643 stock tokens. Includes holder queries, balance lookups, role management, compliance checks, and webhook integrations.
Hybrid on-chain order book trading for tokenized stocks. Manage order books, submit limit and market orders with post-only and self-trade prevention, run periodic auctions, enforce price references, request quotes (RFQ), and query trades, settlements, and custody balances.
Overcollateralized lending markets for tokenized securities. Manage lending pools, monitor positions and health factors, execute liquidations, configure oracle price feeds, and set up automated hooks.
Lending markets collateralized by imported ERC-3643 security tokens. Deploy freeze or custody markets, publish NAV pricing, manage liquidity and loans, and run the operator-driven liquidation settlement workflow.
## HTTP Status Codes
The API uses standard HTTP status codes:
| Code | Meaning |
| ----- | --------------------------------------------- |
| `200` | Request succeeded |
| `201` | Resource created |
| `400` | Invalid request parameters |
| `401` | Missing or invalid API key |
| `403` | Service not enabled or resource access denied |
| `404` | Resource not found |
| `409` | Resource already exists |
| `429` | Rate limit exceeded |
| `500` | Internal server error |
| `502` | Upstream service error |
| `503` | Service temporarily unavailable |
## Write Operations
Endpoints that touch a contract (identity verification, token issuance, redemptions, freezes, force transfers, oracle syncs, market deployments, loans, liquidations) do not execute anything. They return an unsigned payload built against the target contract. You sign it with your registered wallet and broadcast it yourself.
Trusset holds no private key and has no signer. Nothing moves on-chain without a signature you produced.
A write response carries one of four shapes, depending on what the operation needs:
| Shape | Returned when | Payload |
| ------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `SIGN_TRANSACTION` | One transaction is enough | `transaction` (`to`, `data`) and `functionName` |
| `SIGN_TRANSACTIONS` | Several transactions must run in order | `steps`, each holding its own `transaction`, `functionName`, and a `description` where the reason is not obvious |
| `SIGN_TYPED_DATA` | The contract wants a signature, not a transaction | `typedData` (EIP-712 `domain`, `types`, `primaryType`, `message`) and `display` |
| `txData` | Stock tokenization writes | `txData` (`to`, `data`, `value`) |
Multi-step responses are ordered and must be broadcast in sequence. Where a contract pulls tokens from you, the ERC-20 approval is the first step.
Read-only endpoints (balance queries, holder lookups, transfer compliance checks, status lookups, market metrics) return data directly and need no signature.
## Confirming a Transaction
Some endpoints record state once the transaction is mined. To record it, call the same endpoint a second time with the transaction hash in the body:
```json theme={null}
{ "txHash": "0x9f2c...a41b" }
```
Trusset then reads the receipt from the chain and checks that the transaction was mined, succeeded, targeted the expected contract, and called the expected function with the arguments you claimed. Only then does it write to the database and return the mined result, including values that exist only after execution such as `loanId`, `liquidationId`, `auctionId`, and `positionId`.
State is derived from the receipt, never from the request body. A confirm call that fails verification changes nothing.
| Code | HTTP | Meaning |
| ------------------- | ----- | --------------------------------------------------------------------------------------- |
| `INVALID_TX` | `400` | `txHash` is not a well-formed 32-byte hash |
| `TX_REVERTED` | `400` | The transaction was mined but reverted |
| `TX_WRONG_TARGET` | `400` | The transaction was sent to a different contract than the endpoint expects |
| `TX_WRONG_FUNCTION` | `400` | The calldata does not decode against the expected ABI, or calls a different function |
| `TX_NOT_VERIFIED` | `400` | The transaction decoded correctly but acts on a different loan, auction, or liquidation |
| `TX_NOT_FOUND` | `404` | No receipt yet. The transaction is unmined, dropped, or on another network |
`TX_NOT_FOUND` is the expected response when you confirm too early. Wait for one confirmation and retry, rather than treating it as a failure.
## Authorisation Errors
Writes are authorised against the wallets registered on the instance, and against the roles those wallets hold on your contracts.
| Code | HTTP | Meaning |
| -------------------------------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `RELAYER_NOT_CONFIGURED` | `400` | No verified wallet is registered on this instance |
| `SIGNER_NOT_AUTHORIZED` | `403` | The wallet is not an authorised signer on the market oracle. The oracle owner must call `setAuthorizedSigner`. |
| `ROUTER_OPERATOR_ROLE_MISSING` | `400` | The wallet does not hold `OPERATOR_ROLE` on the liquidation router. The error carries `calldata` that grants it. |
| `ROUTER_ADMIN_ROLE_MISSING` | `400` | The wallet does not hold `DEFAULT_ADMIN_ROLE` on the liquidation router. |
| `MISSING_ROLE` | `403` | The wallet does not hold the contract role this operation requires. The error names it in `requiredRole`. |
| `ONCHAIN_SETTLEMENT_UNAVAILABLE` | `409` | The operation settles on-chain but has no wallet in the loop to sign. Order books configured for `OFF_CHAIN` settlement are unaffected. |