# Developer Guide

## Introduction <a href="#introduction" id="introduction"></a>

Welcome to Tokensoft's developer documentation. This guide illustrates how our partners can interact with Tokensoft services programmatically in the following use cases:

* ATS partners whitelisting a user to trade an ERC-1404 digital asset
* Price feed providers querying current and historical asset prices

Note that certain features are restricted: please [contact us](https://tokensoft.typeform.com/to/k2PYz21f) for more instructions on accessing this API.

## Authentication <a href="#authentication" id="authentication"></a>

Almost all API endpoints require API users to authenticate. Each request must include:

* an API key
* the current time
* a signature of the request information by the API secret

The Tokensoft SDK takes care of this logic, and we encourage you to use it.

This is an example request which provides the `access-key`, `access-sign`, and `access-timestamp` headers.

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

```typescript
const fetch = require('node-fetch')
const crypto = require('crypto')

const url = 'https://platform.stagetokensoft.com/graphql'
// access and secret keys obtained from your admin dashboard
const accessKey = 'your access key'
const secretKey = 'your secret key'

// create a signature for the request body
const createSignature = (body, timestamp, secretKey) => {
  const text = timestamp + body
  const hmac = crypto.createHmac('sha256', secretKey)
  hmac.update(text)
  return hmac.digest('hex')
}

const getServerTime = async () => {
  const request = {
    query: '{ time }'
  }
  const body = JSON.stringify(request)
  const options = {
    headers: {
      'Content-Type': 'application/json',
    },
    method: 'post',
    body
  }

  const res = await fetch(url, options)
  const { data } = await res.json()
  return data.time
}

const run = async () => {
  const timestamp = await getServerTime()
  const body = JSON.stringify({ query: '{ currentUser { id email } }' })
  const signature = createSignature(body, String(timestamp), secretKey)

  const options = {
    // include signature and timestamp to request headers
    headers: {
      'access-key': accessKey,
      'access-sign': signature,
      'access-timestamp': timestamp,
      'Content-Type': 'application/json',
    },
    method: 'post',
    body
  }

  try {
    const res = await fetch(url, options)
    console.log('res', res)
    const { data } = await res.json()
    console.log('data', data)
  } catch (e) {
    console.log('e', e)
  }
}

run()
```

{% endtab %}
{% endtabs %}

## SDK <a href="#sdk" id="sdk"></a>

Tokensoft also has an [Javascript SDK](https://www.npmjs.com/package/tokensoft-sdk) which simplifies interactions with the API.

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

```bash
npm install tokensoft-sdk
```

{% endtab %}
{% endtabs %}

```javascript
import TokensoftSDK from 'tokensoft-sdk'
const issuerEndpoint = 'https://app.arcalabs.com'

const sdk = new TokensoftSDK(issuerEndpoint, process.env.KEY_ID, process.env.SECRET_KEY)
```

## Sandbox Environment <a href="#sandbox-environment" id="sandbox-environment"></a>

API integrations should be tested against a Tokensoft sandbox environment before being used in any production environment. Tokensoft also supports the [GraphQL Playground](https://github.com/graphql/graphql-playground) tool for rapid API testing.

### Platform <a href="#platform" id="platform"></a>

The Tokensoft Platform supports token issuers managing digital securities and investors purchasing the securities.

* URL: [demo.stagetokensoft.com](https://demo.stagetokensoft.com/)
* GraphQL Playground: [demo.stagetokensoft.com/graphql](https://demo.stagetokensoft.com/graphql)


---

# 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/untitled.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.