Tutorials

The trust-api is a GraphQL API so you’ll need to use a GraphQL client.

A GraphQL API is easy to work with as it allows:

  1. Self discovery of the API endpoints
  2. Easier versioning of the API
  3. Allows clients to request whatever data they want in (usually) a single call

There are many GraphQL clients available but Postman may be the easier to work with for testing purposes.

You can still use any HTTP client to send the queries as fundamentally GraphQL queries can be sent via HTTP POST and the responses parsed as valid JSON.

The tutorials are designed to help you get started with the basics of the API and assume you have a client that can take a query and variables.

Tutorial 1 - Getting Session Tokens

The trust-api authentication works through a Partial PIN process. This is simply where a users six digit PIN is validated by asking for 2 digits of that PIN. Since you don’t know which digits will be asked for, this is a two stage process.

  1. Request the PIN digits, called a PinChallenge
  2. Obtain the answers from your user and submit the response

Requesting a PinChallenge

To request a PinChallenge, simply issue the following query.

1
2
3
4
5
6
7
query($email: String!) {
getPartialPinChallenge(email: $email) {
sessionToken
firstPinDigitPosition
secondPinDigitPosition
}
}

Variables:

1
2
3
{
"email":"my_users_email@mail.com"
}

This is issuing a query passing in the email of your user and requesting the sessionToken, firstPinDigitPosition and secondPinDigitPosition.

The response to a pinChallenge request will be

1
2
3
4
5
6
7
8
9
{
"data": {
"getPartialPinChallenge": {
"sessionToken": "rE7TqbEqEdt6sTC8jvqcL7Cjq70gkkjWoIw7dfaA...",
"firstPinDigitPosition": "1",
"secondPinDigitPosition": "4"
}
}
}

NB: The sessionToken has been reduced in size.

The sessionToken must be stored and passed back in a subsequent query.

You can see that the response has given us which digits of the PIN we need to return (through the XXXXPinDigitPosition fields ), in this case it’s asking for the first digit and the fourth.

Responding to a PinChallenge

Now, we need to respond to the PinChallenge, so let’s assume the user PIN is 842876.

We can ask our user for those digits requested and submit the following response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
query(
$email: String!
$firstPinDigit: String!
$secondPinDigit: String!
$sessionToken: String!
) {
getAuthenticationTokens(
getAuthenticationTokensInput: {
email: $email
pinChallenge: {
sessionToken: $sessionToken
firstPinDigit: $firstPinDigit
secondPinDigit: $secondPinDigit
}
}
) {
authentication {
enc
iv
tag
}
}
}

Variables:

1
2
3
4
5
6
{
"email":"my_users_email@mail.com",
"firstPinDigit": "8",
"secondPinDigit":"8",
"sessionToken": "rE7TqbEqEdt6sTC8jvqcL7Cjq70gkkjWoIw7dfaA..."
}

This query, is simply passing back the email, sessionToken and the answers to the PinChallenge, and requesting the enc, iv and tag tokens from the authentication type. If you fail to ask for the authentication type you’ll need to start the process again.

Should the PIN be correct, the result will look something like:

1
2
3
4
5
6
7
8
9
10
11
{
"data": {
"getAuthenticationTokens": {
"authentication": {
"enc": "5rfxa4N8aWYS5EWpZuq4pkFoVJx6OLt/...",
"iv": "sEYQMhhDf74XH2ZAmzNtfA==",
"tag": "1uaGcSlMvrQaW18qD/yUcw=="
}
}
}
}

NB: The enc value has been reduced in size.

The enc, iv and tag tokens are now user sessions tokens which you should store and can be used in subsequent Query requests for the user wallet.

Troubleshooting

  • The sessionToken is valid for a short period of time, if it expires you’ll need to start the pinChallenge process again.
  • If you get the PIN wrong 3 times then the account is placed in PIN_RESET mode and the user will need to use the iOS app to reset their PIN.
  • For security reasons, you will NOT be notified if the email address is wrong so please check the email value carefully
  • An incorrect PIN will return an error such as below
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
"data": {
"getAuthenticationTokens": {
"authentication": null
}
},
"errors": [
{
"path": ["getAuthenticationTokens"],
"data": null,
"errorType": "INVALID_PIN",
"errorInfo": null,
],
"message": "Invalid PIN, please try again"
}
]
}

Tutorial 2 - Fetching user details and wallets

Fetching user details

1
2
3
4
5
6
7
query getUserDetails($authentication: AuthenticationInput!) {
user(authentication: $authentication) {
firstName
lastName
email
}
}

Variables:

Please refer to Tutorial 1 how to get the enc, iv and tag authentication tokens.

1
2
3
4
5
6
7
{
"authentication": {
"enc": "<AUTHENTICATION_TOKEN>",
"iv": "<AUTHENTICATION_TOKEN>",
"tag": "<AUTHENTICATION_TOKEN>"
}
}

Fetching user wallets

user/wallets optional arguments

walletId

You can optionally pass in walletId (of type String) to retrieve only the wallet associated with the given walletId (UUID v4)

walletType

You can optionally pass in a walletType (of type WalletType) BLOCKCHAIN or EXCHANGE to retrieve only the wallets matching the given walletType.

See glossary for further wallet definitions

currency:

You can optionally pass in currency (of type String), this is the fiat currency code (ISO 4217 Currency Code) or the asset symbol that you want the value to be in. (Defaults to “GBP”)

Supported currencies: GBP, USD, EUR, AED, CHF, CNY, JPY, BTC, ETH

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
query getWallets($authentication: AuthenticationInput!) {
user(authentication: $authentication) {
wallets {
allWalletsPortfolio {
total {
...amount
}
balances {
...balanceConnection
}
}
items {
name
id
createdAt
updatedAt
transactions {
...transactionConnection
}
... on ExchangeWallet {
exchangeName
}
... on BlockchainWallet {
total {
...amount
}
balances {
...balanceConnection
}
}

}
nextToken
}
}
}

fragment amount on Amount {
value
currency
timestamp
}

fragment balanceConnection on BalanceConnection {
items {
amount {
...amount
}
asset {
displaySymbol
name
iconUrl
type
dateAdded
decimalPlace
contractAddress
chain
}
}
nextToken
}

fragment transactionConnection on TransactionConnection {
items {
from { ...on Address {id} }
to { ...on Address {id} }
amount {
...amount
}
status
createdAt
updatedAt
}
nextToken
}

Variables:

Please refer to Tutorial 1 how to get the enc, iv and tag authentication tokens.

1
2
3
4
5
6
7
{
"authentication": {
"enc": "<AUTHENTICATION_TOKEN>",
"iv": "<AUTHENTICATION_TOKEN>",
"tag": "<AUTHENTICATION_TOKEN>"
}
}

Converting amounts

Amount type is recursive to itself via the in query like so:

1
2
3
4
5
6
type Amount {
value: String
currency: String!
timestamp: String
in(currency: String!): Amount!
}

This allows us to recursively call the in query within the Amount type to convert a value in one currency to another and so on.
Supported currencies: GBP, USD, EUR, AED, CHF, CNY, JPY, BTC, ETH

Display allWalletsPortfolio.total value in BTC then convert to EUR example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
query convertPortfolioTotalAmount(
$authentication: AuthenticationInput!
$currency1: String!
$currency2: String!
) {
user(authentication: $authentication) {
wallets(currency: $currency1) {
allWalletsPortfolio {
total {
...amount
in(currency: $currency2) {
...amount
}
}
}
}
}
}

fragment amount on Amount {
value
currency
timestamp
}

Variables:

Please refer to Tutorial 1 how to get the enc, iv and tag authentication tokens.

1
2
3
4
5
6
7
8
9
{
"authentication": {
"enc": "<AUTHENTICATION_TOKEN>",
"iv": "<AUTHENTICATION_TOKEN>",
"tag": "<AUTHENTICATION_TOKEN>",
},
"currency1": "BTC",
"currency2": "EUR"
}

Display each asset balance item in allWalletsPortfolio.balances in its native token currency then convert it to BTC then to EUR example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
query recursivelyConvertAmount(
$authentication: AuthenticationInput!
$currency1: String!
$currency2: String!
) {
user(authentication: $authentication) {
wallets {
allWalletsPortfolio {
balances {
items {
amount {
...amount
in(currency: $currency1) {
...amount
in(currency: $currency2) {
...amount
}
}
}

}
nextToken
}
}
}
}
}

fragment amount on Amount {
value
currency
timestamp
}

Variables:

Please refer to Tutorial 1 how to get the enc, iv and tag authentication tokens.

1
2
3
4
5
6
7
8
9
{
"authentication": {
"enc": "<AUTHENTICATION_TOKEN>",
"iv": "<AUTHENTICATION_TOKEN>",
"tag": "<AUTHENTICATION_TOKEN>",
},
"currency1": "BTC",
"currency2": "EUR"
}