# 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"
        }
      ]
    }
  }
}

```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://tokensoft.gitbook.io/tokensoft/api/use-cases.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.