> For the complete documentation index, see [llms.txt](https://tokensoft.gitbook.io/tokensoft/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tokensoft.gitbook.io/tokensoft/api/use-cases.md).

# Use Cases

### User Whitelisting <a href="#user-whitelisting" id="user-whitelisting"></a>

Trading venues, such as an ATS, face two challenges when supporting digital asset securities.

First, they have their own AML/KYC compliance programs for their users, so investors buying or selling ERC-1404 digital asset securities might need to submit duplicate AML/KYC information to both the issuer and the ATS, creating a redundant and unnecessarily slow compliance process.

Second, they need to ensure that any on-chain compliance restrictions do not cause trade settlement to fail unexpectedly, so they might need to monitor every security token contract.

Tokensoft’s API solves these problems through the following:

* The API enables approved ATS partners to collaborate with TTA on investor compliance and on-chain whitelisting.
* Issuers can ensure that all transfers meet their compliance requirements,
* An ATS can avoid on-chain token contract management allowing investors to access secondary liquidity for ERC-1404 tokens easily.

ATS partners can use these API endpoints to request on-chain whitelisting of an investor so that they are certain secondary transactions will settle as-expected.

The API collects kyc information about the user as detailed in the example

{% tabs %}
{% tab title="GraphQL" %}

```graphql
mutation {
  whitelistUser(email:"[email protected]", ethAddress:"0x00192fb10df ... 3cd1bf599e8", kyc: {
    firstName:"john",
    lastName:"doe",
    address: {
      streetAddress:"123 abc street",
      city:"San Francisco",
      state:"CA",
      zip:"94000",
      country:"US"
    }
  })
}
```

{% endtab %}

{% tab title="TypeScript" %}

```typescript
// using the tokensoft sdk
const transactionHash = await sdk.authorizeUser(
  '[email protected]',
  '0x00192fb10df ... 3cd1bf599e8',
  {
    firstName:"john",
    lastName:"doe",
    address: {
      streetAddress:"123 abc street",
      city:"San Francisco",
      state:"CA",
      zip:"94000",
      country:"US"
    }
  }
)
```

{% endtab %}
{% endtabs %}

The mutation returns the hash of the add-to-whitelist transaction.

If an error occurred, the mutation returns `null`. (Note: in a future release, an error message and code will be provided)

### Token Pricing <a href="#token-pricing" id="token-pricing"></a>

Token price feed providers can query the current or historical price of a token supported by Tokensoft.

{% tabs %}
{% tab title="GraphQL" %}

```graphql
// Query current price
query getLatestPrice {
  getLatestPrice(symbol: "TSFT")
}

// Query historical prices.
query getTimestampPrice {
  getTimestampPrice(symbol: "usdt", IsoTimestamp:"2020-06-20T03:54:32") {
    arcaPrice
    usdcPrice
  }
}
```

{% endtab %}

{% tab title="Bash" %}

```bash
curl -i -H 'Content-Type: application/json' -X POST -d '{"query": "query {getLatestSupply(product: \"Wrapped ZEC (WZEC)\") {totalSupply, circulatingSupply, dateTime}}"}' https://portal.wrapped.com/graphql
```

{% endtab %}
{% endtabs %}

### Token Supply

The supply of a Token can be queried with the `getSupply` and `getLatestSupply` endpoints. The total supply is the total amount of tokens minted. The circulating supply is the total supply excluding tokens held in reserve accounts.

{% tabs %}
{% tab title="GraphQL" %}

```graphql
query {
  getLatestSupply(product: "INX") {
    totalSupply
    circulatingSupply
  }
}

query {
  getSupply(product:"INX", start: "2019-01-01T00:00:00.000Z", end: "2021-10-21T17:51:44.265Z") {
    totalSupply,
    circulatingSupply,
    dateTime
  }
}

```

{% endtab %}
{% endtabs %}

### KYC Check Status <a href="#kyc-check-status" id="kyc-check-status"></a>

This is a Platform Specific API Endpoint to allow querying the status of a user's KYC check.

The calling account must be authorized to view KYC status on the user being requested.

Results are shown in a `breakdown` and `subBreakdowns` arrays that details which specific checks passed or failed.

```graphql
query{
 getKycCheck(id: "CHECK_ID"){
  id,
  reports{
    id
    createdAt,
    breakdown{
      name
      result
      properties {
        key
        value
      }
      subBreakDowns{
        name
        result
        properties{
          key
          value
        }
      }
    }
  }
}
}

result:

{
  "data": {
    "getKycCheck": {
      "id": "ids321",
      "reports": [
        {
          "breakdown": [
            {
              "name": "date_of_birth",
              "properties": [],
              "result": "unidentified",
              "subBreakDowns": [
                {
                  "name": "date_of_birth_matched",
                  "properties": [],
                  "result": null
                }
              ]
            },
            {
              "name": "address",
              "properties": [],
              "result": "clear",
              "subBreakDowns": [
                {
                  "name": "address_matched",
                  "properties": [
                    {
                      "key": "sources",
                      "value": "Credit Agencies"
                    }
                  ],
                  "result": "clear"
                }
              ]
            }
          ],
          "createdAt": "2019-11-07T18:03:40Z",
          "id": "ids123"
        }
      ]
    }
  }
}

```