Trusset Protocol - Infrastructure for Asset Tokenization

GET

orderbooks

external-securities

api

order-books

{orderBookId}

security

curl "https://api.trusset.org/orderbooks/external-securities/api/order-books/clx_ob_extsec_001/security?userAddress=0xabc7f1093d5e26b804a1c3f78de025916b47c0d3" \
  -H "X-API-Key: trusset_your_key_here"

const res = await fetch(
  `https://api.trusset.org/orderbooks/external-securities/api/order-books/${orderBookId}/security?userAddress=${address}`,
  { headers: { 'X-API-Key': 'trusset_your_key_here' } }
);
const { data } = await res.json();

const signature = await signer._signTypedData(data.eip712.domain, data.eip712.types, order);

{
  "success": true,
  "data": {
    "orderBookId": "clx_ob_extsec_001",
    "custodyContract": "0x489aee4ae9546081d55848f157e03192e826988c",
    "tokenAddress": "0x51f2b9d0e77c4a1b83ce6d4a9271e5f3a0c8b912",
    "quoteTokenAddress": "0x98ad0ca091552e23c564b41c74282e5343d03e8a",
    "underlyingIdentifier": "CH0012032048",
    "baseDecimals": 18,
    "quoteDecimals": 6,
    "settlementOperator": "0x5ad87a0621175206b72d10e4b8577b192e7f40ab",
    "security": {
      "admin": "0x7712db30a7b4ffd9c445793089118b60e56d752a",
      "isin": "CH0012032048",
      "isinRaw": "0x4348303031323033323034380000000000000000000000000000000000000000",
      "baseUnit": "1000000000000000000",
      "registered": true,
      "active": true
    },
    "eip712": {
      "domain": {
        "name": "TRexCustody",
        "version": "1",
        "chainId": 11155111,
        "verifyingContract": "0x489AeE4ae9546081d55848F157E03192e826988c"
      },
      "types": {
        "Order": [
          { "name": "trader", "type": "address" },
          { "name": "token", "type": "address" },
          { "name": "quote", "type": "address" },
          { "name": "isBuy", "type": "bool" },
          { "name": "quantity", "type": "uint256" },
          { "name": "price", "type": "uint256" },
          { "name": "expiry", "type": "uint64" },
          { "name": "nonce", "type": "uint64" },
          { "name": "salt", "type": "bytes32" }
        ]
      }
    },
    "balances": {
      "base": {
        "total": "500000000000000000000",
        "locked": "0",
        "onChainAvailable": "500000000000000000000",
        "reserved": "20000000000000000000",
        "available": "480000000000000000000"
      },
      "quote": {
        "total": "100000000000",
        "locked": "0",
        "onChainAvailable": "50000000000",
        "reserved": "0",
        "available": "50000000000"
      }
    },
    "quoteAllowance": "50000000000"
  }
}

Returns everything a client needs to build and sign an order for this book: the security’s live registration state, the exact EIP-712 domain and type definitions the custody contract expects, and, when you name a wallet, that wallet’s tradable balances and its settlement asset allowance. Use it before Prepare Order if you want to build the typed data yourself, and to show a trader what they can actually trade.

Path Parameters

string

required

Order book ID.

Query Parameters

string

Wallet to report balances for. Omit for the registration and domain data only.

Response Fields

object

Show child attributes

string

Order book ID.

string

Custody contract the book settles through.

string

Security token.

string

Settlement asset.

string

Identifier recorded on the book.

integer

Security token decimals.

integer

Settlement asset decimals.

string

Wallet authorized to sign settlements.

object

Live state read from the custody contract.

Show child attributes

string

Security admin recorded at registration.

string

Identifier as a readable string.

string

The same identifier as the raw 32-byte value.

string

One whole unit of the security, in base units.

boolean

Whether the security is registered.

boolean

Whether the issuer still permits venue trading.

object

Show child attributes

object

name is TRexCustody, version is 1, chainId is your instance’s chain, and verifyingContract is the custody contract.

object

The Order struct: trader and token and quote as addresses, isBuy as a bool, quantity and price as uint256, expiry and nonce as uint64, and salt as bytes32, in that order.

object

Present only when userAddress was supplied.

Show child attributes

object

Security balances, in the security’s base units, carrying total, locked, onChainAvailable, reserved and available.

object

Settlement asset balances, same shape, in the asset’s base units.

string

Present only when userAddress was supplied. What the wallet has approved the custody contract to spend of the settlement asset, in base units.

Reading the balances

onChainAvailable is what the contract reports. reserved is what this venue has committed to the wallet’s own resting orders. available is the difference, and is the number an order is checked against. For the settlement asset, the contract’s available figure is already the lesser of balance and allowance, so a wallet with plenty of tokens but no approval reads as zero. Raise it with Approve Settlement Asset.

A balance read that fails answers with zeros rather than an error. Treat an unexpected zero as suspect if the wallet is known to be funded, and check Get Trade Readiness, which does surface a chain failure explicitly.

curl "https://api.trusset.org/orderbooks/external-securities/api/order-books/clx_ob_extsec_001/security?userAddress=0xabc7f1093d5e26b804a1c3f78de025916b47c0d3" \
  -H "X-API-Key: trusset_your_key_here"

const res = await fetch(
  `https://api.trusset.org/orderbooks/external-securities/api/order-books/${orderBookId}/security?userAddress=${address}`,
  { headers: { 'X-API-Key': 'trusset_your_key_here' } }
);
const { data } = await res.json();

const signature = await signer._signTypedData(data.eip712.domain, data.eip712.types, order);

{
  "success": true,
  "data": {
    "orderBookId": "clx_ob_extsec_001",
    "custodyContract": "0x489aee4ae9546081d55848f157e03192e826988c",
    "tokenAddress": "0x51f2b9d0e77c4a1b83ce6d4a9271e5f3a0c8b912",
    "quoteTokenAddress": "0x98ad0ca091552e23c564b41c74282e5343d03e8a",
    "underlyingIdentifier": "CH0012032048",
    "baseDecimals": 18,
    "quoteDecimals": 6,
    "settlementOperator": "0x5ad87a0621175206b72d10e4b8577b192e7f40ab",
    "security": {
      "admin": "0x7712db30a7b4ffd9c445793089118b60e56d752a",
      "isin": "CH0012032048",
      "isinRaw": "0x4348303031323033323034380000000000000000000000000000000000000000",
      "baseUnit": "1000000000000000000",
      "registered": true,
      "active": true
    },
    "eip712": {
      "domain": {
        "name": "TRexCustody",
        "version": "1",
        "chainId": 11155111,
        "verifyingContract": "0x489AeE4ae9546081d55848F157E03192e826988c"
      },
      "types": {
        "Order": [
          { "name": "trader", "type": "address" },
          { "name": "token", "type": "address" },
          { "name": "quote", "type": "address" },
          { "name": "isBuy", "type": "bool" },
          { "name": "quantity", "type": "uint256" },
          { "name": "price", "type": "uint256" },
          { "name": "expiry", "type": "uint64" },
          { "name": "nonce", "type": "uint64" },
          { "name": "salt", "type": "bytes32" }
        ]
      }
    },
    "balances": {
      "base": {
        "total": "500000000000000000000",
        "locked": "0",
        "onChainAvailable": "500000000000000000000",
        "reserved": "20000000000000000000",
        "available": "480000000000000000000"
      },
      "quote": {
        "total": "100000000000",
        "locked": "0",
        "onChainAvailable": "50000000000",
        "reserved": "0",
        "available": "50000000000"
      }
    },
    "quoteAllowance": "50000000000"
  }
}

Error Codes

Code	HTTP	Cause
`VALIDATION_ERROR`	`400`	`userAddress` is not a valid address
`ORDER_BOOK_NOT_FOUND`	`404`	No such external securities book on this instance, and not imported
`CHAIN_UNAVAILABLE`	`502`	The custody contract could not be read
`SERVICE_NOT_ENABLED`	`403`	The Trading service is not enabled on this instance

curl "https://api.trusset.org/orderbooks/external-securities/api/order-books/clx_ob_extsec_001/security?userAddress=0xabc7f1093d5e26b804a1c3f78de025916b47c0d3" \
  -H "X-API-Key: trusset_your_key_here"

const res = await fetch(
  `https://api.trusset.org/orderbooks/external-securities/api/order-books/${orderBookId}/security?userAddress=${address}`,
  { headers: { 'X-API-Key': 'trusset_your_key_here' } }
);
const { data } = await res.json();

const signature = await signer._signTypedData(data.eip712.domain, data.eip712.types, order);

{
  "success": true,
  "data": {
    "orderBookId": "clx_ob_extsec_001",
    "custodyContract": "0x489aee4ae9546081d55848f157e03192e826988c",
    "tokenAddress": "0x51f2b9d0e77c4a1b83ce6d4a9271e5f3a0c8b912",
    "quoteTokenAddress": "0x98ad0ca091552e23c564b41c74282e5343d03e8a",
    "underlyingIdentifier": "CH0012032048",
    "baseDecimals": 18,
    "quoteDecimals": 6,
    "settlementOperator": "0x5ad87a0621175206b72d10e4b8577b192e7f40ab",
    "security": {
      "admin": "0x7712db30a7b4ffd9c445793089118b60e56d752a",
      "isin": "CH0012032048",
      "isinRaw": "0x4348303031323033323034380000000000000000000000000000000000000000",
      "baseUnit": "1000000000000000000",
      "registered": true,
      "active": true
    },
    "eip712": {
      "domain": {
        "name": "TRexCustody",
        "version": "1",
        "chainId": 11155111,
        "verifyingContract": "0x489AeE4ae9546081d55848F157E03192e826988c"
      },
      "types": {
        "Order": [
          { "name": "trader", "type": "address" },
          { "name": "token", "type": "address" },
          { "name": "quote", "type": "address" },
          { "name": "isBuy", "type": "bool" },
          { "name": "quantity", "type": "uint256" },
          { "name": "price", "type": "uint256" },
          { "name": "expiry", "type": "uint64" },
          { "name": "nonce", "type": "uint64" },
          { "name": "salt", "type": "bytes32" }
        ]
      }
    },
    "balances": {
      "base": {
        "total": "500000000000000000000",
        "locked": "0",
        "onChainAvailable": "500000000000000000000",
        "reserved": "20000000000000000000",
        "available": "480000000000000000000"
      },
      "quote": {
        "total": "100000000000",
        "locked": "0",
        "onChainAvailable": "50000000000",
        "reserved": "0",
        "available": "50000000000"
      }
    },
    "quoteAllowance": "50000000000"
  }
}

Overview

MiCA Register

Customers

Stock Tokenization

Stock Trading

External Securities Trading

Commodity Trading

Stock Lending

External Securities Lending

Vaults

Get Security Status

Path Parameters

Query Parameters

Response Fields

Reading the balances

Error Codes

​Path Parameters

​Query Parameters

​Response Fields

​Reading the balances

​Error Codes

Path Parameters

Query Parameters

Response Fields

Reading the balances

Error Codes