# Wallet Manager API

## General API information

The Wallet Manager API that serves for creating and managing Your wallet:

* Registration and account management
* Cryptocurrency buy/sell orders
* Working with external wallets
* Ability to update rate information

## HTTP Return Codes

* HTTP `4XX` return codes are used for malformed requests;

  the issue is on the sender's side.
* HTTP `400` return code is used when the WAF Limit (Web Application Firewall) has been violated.
* HTTP `404` return code is used when requested data not found.
* HTTP `408` return code is used when request timeout exceeded.
* HTTP `5XX` return codes are used for internal errors; the issue is on

  Zam's side.

  It is important to **NOT** treat this as a failure operation; the execution status is

  **UNKNOWN** and could have been a success.
* HTTP `500` return code is used when internal server error occured.
* HTTP `503` return code is used when requested service is unreachable.

## Error Codes

* Any endpoint can return an ERROR

Sample Payload below:

```javascript
{
 "meta": {
  "status": "OK",
  "message": "ERROR - Authorization error"
 },
 "data": {}
}
```

## Common response parts

The response always consist of two objects `meta` and `data`.

The `meta` object has two parameters `status` that could be `"OK"` or `"ERROR"` and `message` with status describtion values: `"SUCCESS"` `"Not found"` and etc.. `data` object will contain either no object or response's payload.

## API methods

The API contains wallet management methods such as account administration, ordering transactions, adding/deleting external wallets and etc..

### Account management requests

#### New User registration

New user registration request.

Request type and URL:

```
POST https://zam.io/api/auth
```

Request parameters:

| Name        | Type   | Description                                                                          |
| ----------- | ------ | ------------------------------------------------------------------------------------ |
| phone       | STRING | User’s phone number. Should contain at least 10 characters.                          |
| fullName    | STRING | User’s full name(Surname, Name, Patronymic/Middle Name).                             |
| refCode     | STRING | The referral code that user received if was invited.                                 |
| codeRequest | OBJECT | Subrequest for number verification. Contains “phone” field that was mentioned above. |

Request example:

```javascript
    {
      "phone": "0647744360",
      "fullName": "Name Surname",
      "refCode": "{referral code}",
      "codeRequest": 
      {
       "phone": "0647744360"
      }
    }
```

Response parameters:

| Name            | Type   | Description                                                                  |
| --------------- | ------ | ---------------------------------------------------------------------------- |
| passportMessage | STRING | Passport phrase.                                                             |
| agreement       | OBJECT | An `agreement` object that consist of parameters describet below.            |
| id              | STRING | UUID of agreement document. Example: `173e4567-e89b-12d3-a456-426624174000`. |
| name            | STRING | The agreement file name.                                                     |
| url             | STRING | The agreement file's URL.                                                    |

Response example:

```javascript
    {
     "meta": 
     {
      "status": "OK",
      "message": "Success"
     },
     "data": 
     {
      "passportMessage": "Passport phrase",
      "agreement": 
      {
       "id": "173e4567-e89b-12d3-a456-426624174000",
       "name": "Security agreement",
       "url": "/api/auth/documents/173e4567-e89b-12d3-a456-426614174000"
      }
     }
    }
```

#### Password change

Simple password change request.

Request type and URL:

```
POST https://zam.io/api/auth/change
```

Request parameters:

| Name        | Type   | Description          |
| ----------- | ------ | -------------------- |
| oldPassword | STRING | Old password's hash. |
| newPassword | STRING | New password's hash. |

Request example:

```javascript
    {
     "oldPassword": "839a54bf20626e4942bc8f11873f0654",
     "newPassword": "fb29ed3264c5a92bcf74eccd7489e828"
    }
```

Response example:

```javascript
    {
     "meta": 
     {
      "status": "OK",
      "message": "Success"
     }
    }
```

#### Request for security agreements

Security agreement for user to accept.

Request type and URL:

```
 GET https://zam.io/api/auth/documents/:documentId
```

The response returns security agreement file to download.

#### Delete account

Request to delete authorized account.

Request type and URL:

```
DELETE https://zam.io/api/auth/delete
```

Response example:

```javascript
{
 "meta": {
  "status": "OK",
  "message": "Success"
 },
 "data": {}
}
```

#### Generate private key

Request for Zam wallet's private key generation

Request type and URL:

```
GET https://zam.io/api/auth/privateKey
```

Response parameters:

| Name       | Type   | Description               |
| ---------- | ------ | ------------------------- |
| privateKey | STRING | Zam wallet's private key. |

Response example:

```javascript
{
 "meta": {
  "status": "OK",
  "message": "Success"
 },
 "data": {
  "privateKey": "bd0c8e3bd998a500b0984584a7245ca0"
 }
}
```

#### Update token

Request for authorization token.

Request type and URL:

```
POST https://zam.io/api/auth/token
```

Request parameters:

| Name     | Type   | Description              |
| -------- | ------ | ------------------------ |
| token    | STRING | Last expired token.      |
| deviceId | STRING | Device’s UUID.           |
| login    | STRING | User’s login.            |
| password | STRING | Hash of user’s password. |

Request example:

```javascript
{
    "token": "94a08da1fecbb6e8b46990538c7b50b2",
    "deviceId": "123e4567-e89b-12d3-a456-426614174000",
    "login": "UserName",
    "password": "fb29ed3264c5a92bcf74eccd7489e828"
}
```

Response parameters:

| Name      | Type   | Description                                                                  |
| --------- | ------ | ---------------------------------------------------------------------------- |
| token     | STRING | Last expired token.                                                          |
| agreement | OBJECT | An object with three parameters described.                                   |
| id        | STRING | UUID of agreement document. Example: `173e4567-e89b-12d3-a456-426624174000`. |
| name      | STRING | The agreement file name.                                                     |
| url       | STRING | The agreement file's URL.                                                    |

Response example:

```javascript
{
 "meta": {
  "status": "OK",
  "message": "Success"
 },
 "data": {
  "token": "94a08da1fecbb6e8b46990538c7b50b2",
  "agreement": {
   "id": "173e4567-e89b-12d3-a456-426624174000",
   "name": "Security agreement",
   "url": "/api/auth/documents/173e4567-e89b-12d3-a456-426614174000"
  }
 }
}
```

### Order requests

#### Request for transaction order generation

Request for transaction order to buy/sell cryptocurrency. Headers of request are described below Here should be table

Request parameters:

| Name                | Type   | Description                                                    | Example                                       |
| ------------------- | ------ | -------------------------------------------------------------- | --------------------------------------------- |
| priority            | STRING | Transaction priority (default value - MEDIUM, optional - TOP). | MEDIUM                                        |
| blockchainFrom      | STRING | Source platform name.                                          | Binance                                       |
| blockchainTo        | STRING | Destination platform name.                                     | Binance                                       |
| addressContractFrom | STRING | Contract adrress on source wallet.                             |                                               |
| addressContractTo   | STRING | Contract address on destiantion wallet.                        |                                               |
| adressFrom          | STRING | Soruce wallet address.                                         | cosmos18ta688t40kmped54stvdgvgrazmyh0zqwhmhf5 |
| addressTo           | STRING | Destionation wallet address.                                   | 12PUTiN2VjQQzkmSNU7AauHNrQSuadbmhH            |
| currency            | STRING | Cryptocurrency shortname.                                      | BTC                                           |
| amount              | STRING | Cryptrocurrency amount.                                        | 3.45                                          |
| dateCreate          | STRING | Order creation date:time.                                      | 1947-04-26T15:41:07.646Z                      |

Request type and URL:

```
GET https://zam.io/api/order?priority=MEDIUM&blockchainFrom=string&blockchainTo=string&addressContractFrom=string&addressContractTo=string&adressFrom=string&addressTo=string&amount=string&paymentRestrictionTransaction=string
```

Response parameters:

| Name                | Type   | Description                             |
| ------------------- | ------ | --------------------------------------- |
| blockchainFrom      | STRING | Source platform name                    |
| blockchainTo        | STRING | Destination platform name.              |
| addressTo           | STRING | Destionation wallet address.            |
| amount              | STRING | Cryptrocurrency amount.                 |
| dateCreate          | STRING | Order creation date:time.               |
| addressContractFrom | STRING | Contract adrress on source wallet.      |
| addressContractTo   | STRING | Contract address on destiantion wallet. |
| adressFrom          | STRING | Soruce wallet address.                  |
| currency            | STRING | Cryptocurrency shortname.               |

Response example:

```javascript
{
 "meta": {
  "status": "OK",
  "message": "Success"
 },
 "data": {
  "blockchainFrom": "",
  "blockchainTo": "",
  "addressTo": "",
  "amount": "34.00",
  "dateCreate": "1947-04-26T15:41:07.646Z",
  "addressContractFrom": "",
  "addressContractTo": "",
  "adressFrom": "",
  "currency": "USD"
 }
}
```

#### Order for cryptocurrency buy

The buy operation that follows after receiving transaction order.

Request parameters:

| Name              | Type   | Description                                                    | Example                            |
| ----------------- | ------ | -------------------------------------------------------------- | ---------------------------------- |
| priority          | STRING | Transaction priority (default value - MEDIUM, optional - TOP). | MEDIUM                             |
| blockchainTo      | STRING | Destination platform name.                                     | Binance                            |
| addressContractTo | STRING | Contract address on destiantion wallet.                        |                                    |
| addressTo         | STRING | Destionation wallet address.                                   | 12PUTiN2VjQQzkmSNU7AauHNrQSuadbmhH |
| currency          | STRING | Cryptocurrency shortname.                                      | BTC                                |
| amount            | STRING | Cryptrocurrency amount.                                        | 3.45                               |
| dateCreate        | STRING | Order creation date:time.                                      | 1947-04-26T15:41:07.646Z           |
| order             | STRING | Reference to transaction order for payment.                    |                                    |

Request type and URL:

```
PUT https://zam.io/api/order/purchase?priority=MEDIUM&blockchainTo=string&addressContractTo=string&addressTo=string&amount=string&paymentRestrictionTransaction=string
```

Response parameters:

| Name              | Type   | Description                                 |
| ----------------- | ------ | ------------------------------------------- |
| blockchainTo      | STRING | Destination platform name.                  |
| addressTo         | STRING | Destionation wallet address.                |
| amount            | STRING | Cryptrocurrency amount.                     |
| dateCreate        | STRING | Order creation date:time.                   |
| order             | STRING | Reference to transaction order for payment. |
| addressContractTo | STRING | Contract address on destiantion wallet.     |
| currency          | STRING | Cryptocurrency shortname.                   |

Response example:

```javascript
{
 "meta": {
  "status": "OK",
  "message": "Success"
 },
 "data": {
  "blockchainTo": "",
  "addressTo": "",
  "amount": "34.00",
  "dateCreate": "1947-04-26T15:41:07.646Z",
  "order": "",
  "addressContractTo": "",
  "currency": "USD"
 }
}
```

#### Order for cryptocurrency sell

The sell operation that follows after receiving transaction order. FPS - Fast Payment System

Request type and URL:

```
PUT https://zam.io/api/order/sale?priority=MEDIUM&blockchainFrom=string&blockchainTo=string&addressContractFrom=string&addressContractTo=string&adressFrom=string&addressTo=string&amount=string&paymentRestrictionTransaction=string
```

Request parameters:

| Name                       | Type   | Description                     |
| -------------------------- | ------ | ------------------------------- |
| spbPhone1                  | STRING | Phone number registered on FPS. |
| spbName1                   | STRING | Full name registered on on FPS. |
| visaCardNumber2            | STRING | 16 digit card number.           |
| visaName2                  | STRING | Fullname of card holder.        |
| masterCardNumber3          | STRING | 16 digit card number.           |
| bankAccountPaymentAccount4 | STRING |                                 |
| bankAccountBIK4            | STRING |                                 |
| bankAccountName4           | STRING |                                 |

Request example:

```javascript
{
    "spbPhone1": "",
    "spbName1": "",
    "visaCardNumber2": "0000 0000 0000 0000",
    "visaName2": "Name Surname",
    "masterCardNumber3": "0000 0000 0000 0000",
    "masterName3": "Name Surname",
    "bankAccountPaymentAccount4": "",
    "bankAccountBIK4": "",
    "bankAccountName4": ""
}
```

Response parameters:

| Name                | Type   | Description                                                    |
| ------------------- | ------ | -------------------------------------------------------------- |
| priority            | STRING | Transaction priority (default value - MEDIUM, optional - TOP). |
| blockchainFrom      | STRING | Source platform name.                                          |
| blockchainTo        | STRING | Destination platform name.                                     |
| addressTo           | STRING | Destionation wallet address.                                   |
| amount              | STRING | Cryptrocurrency amount.                                        |
| dateCreate          | STRING | Order creation date:time.                                      |
| addressContractFrom | STRING | Contract adrress on source wallet.                             |
| addressContractTo   | STRING | Contract address on destiantion wallet.                        |
| adressFrom          | STRING | Soruce wallet address.                                         |
| currency            | STRING | Cryptocurrency shortname.                                      |

Response example:

```javascript
{
 "meta": {
  "status": "OK",
  "message": "Success"
 },
 "data": {
  "blockchainFrom": "",
  "blockchainTo": "",
  "addressTo": "",
  "amount": "34.00",
  "dateCreate": "1947-04-26T15:41:07.646Z",
  "addressContractFrom": "",
  "addressContractTo": "",
  "adressFrom": "",
  "currency": "USD"
 }
}
```

### Enable or Disable external wallets

#### Enable external wallet

Request for adding external wallet.

Request type and URL:

```
POST https://zam.io/api/otherCrypto
```

Request parameters:

| Name            | Type   | Description                |
| --------------- | ------ | -------------------------- |
| blockchain      | STRING | Platform name.             |
| addressContract | STRING | Wallet’s contract address. |
| adress          | STRING | Wallet's adress.           |

Request example:

```javascript
{
 "blockchain": "Zam",
 "addressContract": "",
 "adress": ""
}
```

Response example:

```javascript
{
 "meta": {
  "status": "OK",
  "message": "Success"
 },
 "data": {}
}
```

#### Disable external wallet

Request to disable external wallet. Headers are described below.

Request parameters:

| Name            | Type   | Description                |
| --------------- | ------ | -------------------------- |
| blockchain      | STRING | Platform name.             |
| addressContract | STRING | Wallet’s contract address. |
| adress          | STRING | Wallet's adress.           |

Request type and URL:

```
DELETE https://zam.io/api/otherCrypto?blockchain=string&addressContract=string&address=string
```

Response example:

```javascript
{
 "meta": {
  "status": "OK",
  "message": "Success"
 },
 "data": {}
}
```

### Request for rate information

#### Get top50 cryptocurrenies' information

Request for top 50 crypto currencies with currency to Zam/dollar rate.

Request type and URL:

```
GET https://zam.io/api/rate
```

Response is an object array of currencies' describtions and rate data. Parameters:

| Name            | Type   | Description                               |
| --------------- | ------ | ----------------------------------------- |
| blockchain      | STRING | Platform name.                            |
| address         | STRING | Wallet's adress.                          |
| currency        | STRING | Cryptocurrency shortname.                 |
| rateToDollar    | STRING | Rate to dollar.                           |
| rateToZam       | STRING | Rate to Zam.                              |
| amount          | STRING | Cryptrocurrency amount.                   |
| dateCreate      | STRING | Date:time of exchange rate actualization. |
| addressContract | STRING | Wallet’s contract address.                |

Response example:

```javascript
{
 "meta": {
  "status": "OK",
  "message": "Success"
 },
 "data": [
  {
   "blockchain": "BTC",
   "address": "",
   "currency": "BTC",
   "rateToDollar": "100000.00",
   "rateToZam": "0.5",
   "amount": "34.5",
   "dateRate": "1947-04-26T15:41:07.646Z",
   "addressContract": ""
  },
  {
   "blockchain": "ETH",
   "address": "",
   "currency": "BTC",
   "rateToDollar": "200",
   "rateToZam": "0.005",
   "amount": "34.5",
   "dateRate": "1947-04-26T15:41:07.646Z",
   "addressContract": ""
  }
 ]
}
```

#### Selected cryptocurrency to dollar rate

Gets rate to dollar. Headers are described below.

Request parameters:

| Name            | Type   | Description                |
| --------------- | ------ | -------------------------- |
| currency        | STRING | Cryptocurrency shortname.  |
| blockchain      | STRING | Platform name.             |
| addressContract | STRING | Wallet’s contract address. |

Request type and URL:

```
GET https://zam.io/api/rate/dollar?currency=string&blockchain=string&addressContract=string
```

Response parameters:

| Name            | Type   | Description                               |
| --------------- | ------ | ----------------------------------------- |
| blockchain      | STRING | Platform name.                            |
| address         | STRING | Wallet's adress.                          |
| currency        | STRING | Cryptocurrency shortname.                 |
| rateToDollar    | STRING | Rate to dollar.                           |
| rateToZam       | STRING | Rate to Zam.                              |
| amount          | STRING | Cryptrocurrency amount.                   |
| dateCreate      | STRING | Date:time of exchange rate actualization. |
| addressContract | STRING | Wallet’s contract address.                |

Response example:

```javascript
{
 "meta": {
  "status": "OK",
  "message": "Success"
 },
 "data":{
  "blockchain": "ETH",
  "address": "",
  "currency": "BTC",
  "rateToDollar": "200",
  "rateToZam": "0.005",
  "amount": "34.5",
  "dateRate": "1947-04-26T15:41:07.646Z",
  "addressContract": ""
 }
}
```

#### Selected cryptocurrency to Zam rate

Gets rate to Zam. Headers are described below.

Request parameters:

| Name            | Type   | Description                |
| --------------- | ------ | -------------------------- |
| currency        | STRING | Cryptocurrency shortname.  |
| blockchain      | STRING | Platform name.             |
| addressContract | STRING | Wallet’s contract address. |

Request type and URL:

```
GET https://zam.io/api/rate/zam?currency=string&blockchain=string&addressContract=do dipisicing
```

Response parameters:

| Name            | Type   | Description                               |
| --------------- | ------ | ----------------------------------------- |
| blockchain      | STRING | Platform name.                            |
| address         | STRING | Wallet's adress.                          |
| currency        | STRING | Cryptocurrency shortname.                 |
| rateToDollar    | STRING | Rate to dollar.                           |
| rateToZam       | STRING | Rate to Zam.                              |
| amount          | STRING | Cryptrocurrency amount.                   |
| dateCreate      | STRING | Date:time of exchange rate actualization. |
| addressContract | STRING | Wallet’s contract address.                |

Response example:

```javascript
{
 "meta": {
  "status": "OK",
  "message": "Success"
 },
 "data":{
  "blockchain": "ETH",
  "address": "",
  "currency": "BTC",
  "rateToDollar": "200",
  "rateToZam": "0.005",
  "amount": "34.5",
  "dateRate": "1947-04-26T15:41:07.646Z",
  "addressContract": ""
 }
}
```

### Amount information

#### Balance check on all connected wallets

Request for balance information on all enabled wallets.

Request type and URL:

```
GET https://zam.io/api/amount
```

Request is an array of objects that describes wallet data. Parameters:

Response parameters:

| Name            | Type   | Description                |
| --------------- | ------ | -------------------------- |
| blockchain      | STRING | Platform name.             |
| address         | STRING | Wallet's adress.           |
| currency        | STRING | Cryptocurrency shortname.  |
| amount          | STRING | Cryptrocurrency amount.    |
| addressContract | STRING | Wallet’s contract address. |

Response example:

```javascript
{
 "meta": {
  "status": "OK",
  "message": "Success"
 },
 "data": [
  {
   "blockchain": "BTC",
   "address": "",
   "currency": "BTC",
   "amount": "34.56",
   "addressContract": ""
  },
  {
   "blockchain": "Zam",
   "address": "",
   "currency": "Zam",
   "amount": "34.56",
   "addressContract": ""
  }
 ]
}
```

### History

#### Transaction history for selected wallet

Request type and URL:

```
GET https://zam.io/api/history
```

Response example:

```javascript
{
 "meta": {
  "status": "OK",
  "message": "Success"
 },
 "data": [
  {
   "blockchainFrom": "BTC",
   "blockchainTo": "Zam",
   "addressTo": "",
   "amount": "34.56",
   "commission": [
    {
     "paymentTransaction": "",
     "commissionTransaction": ""
    },
    {
     "paymentTransaction": "",
     "commissionTransaction": ""
    }
   ],
   "dateCreate": "1947-04-26T15:41:07.646Z",
   "dateConfirm": "1947-04-26T15:41:07.646Z",
   "addressContractFrom": "",
   "addressContractTo": "",
   "adressFrom": "",
   "currency": ""
  },
  {
   "blockchainFrom": "ETH",
   "blockchainTo": "Zam",
   "addressTo": "",
   "amount": "34.56",
   "commission": [
    {
     "paymentTransaction": "",
     "commissionTransaction": ""
    },
    {
     "paymentTransaction": "",
     "commissionTransaction": ""
    }
   ],
   "dateCreate": "1947-04-26T15:41:07.646Z",
   "dateConfirm": "1947-04-26T15:41:07.646Z",
   "addressContractFrom": "",
   "addressContractTo": "",
   "adressFrom": "",
   "currency": ""
  }
 ]
}
```

### Notifications management

#### Update notifications

Request type and URL:

```
GET https://zam.io/api/notifications?offset=0&limit=10
```

Response example:

```javascript
{
 "meta": {
  "status": "OK",
  "message": "Success"
 },
 "data": {
  "notifications": [
   {
    "title": "Money purchase",
    "text": "2.1 ETH were purchased to Your wallet (address ...), from address ... в 09:02:57 18.06.2021y.",
    "date": "2020-10-05T10:04:07.666Z",
    "read": true
   },
   {
    "title": "Money purchase",
    "text": "2.1 ETH were purchased to Your wallet (address ...), from address ... в 09:02:57 18.06.2021y.",
    "date": "1947-04-26T15:41:07.646Z",
    "read": true
   }
  ],
  "pagination": {
   "offset": 0,
   "limit": 10,
   "total": 100
  }
 }
}
```

### Calculation requests

#### Transaction information request

Request to get approximate rate and cost of transaction. Headers are described below.

Request parameters:

| Name                          | Type   | Description                                                    | Example                                       |
| ----------------------------- | ------ | -------------------------------------------------------------- | --------------------------------------------- |
| priority                      | STRING | Transaction priority (default value - MEDIUM, optional - TOP). | MEDIUM                                        |
| blockchainFrom                | STRING | Source platform name.                                          | Binance                                       |
| blockchainTo                  | STRING | Destination platform name.                                     | Binance                                       |
| addressContractFrom           | STRING | Contract adrress on source wallet.                             |                                               |
| addressContractTo             | STRING | Contract address on destiantion wallet.                        |                                               |
| adressFrom                    | STRING | Soruce wallet address.                                         | cosmos18ta688t40kmped54stvdgvgrazmyh0zqwhmhf5 |
| addressTo                     | STRING | Destionation wallet address.                                   | 12PUTiN2VjQQzkmSNU7AauHNrQSuadbmhH            |
| currency                      | STRING | Cryptocurrency shortname.                                      | BTC                                           |
| amount                        | STRING | Cryptrocurrency amount.                                        | 3.45                                          |
| paymentRestrictionTransaction | STRING | Payment limit for transaction.                                 | 5.147                                         |

Request type and URL:

```
GET https://zam.io/api/calculation?priority=MEDIUM&blockchainFrom=string&blockchainTo=string&addressContractFrom=string&addressContractTo=string&adressFrom=string&addressTo=string&amount=string&paymentRestrictionTransaction=string
```

Response example:

```javascript
{
 "meta": {
  "status": "OK",
  "message": "Success"
 },
 "data": {
  "blockchainFrom": "",
  "blockchainTo": "",
  "addressTo": "",
  "amount": "",
  "commission": [
   {
    "paymentTransaction": "",
    "commissionTransaction": ""
   },
   {
    "paymentTransaction": "",
    "commissionTransaction": ""
   }
  ],
  "dateActual": "1947-04-26T15:41:07.646Z",
  "addressContractFrom": "",
  "addressContractTo": "",
  "adressFrom": "",
  "currency": ""
 }
}
```


---

# 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://docs.zam.io/ecosystem/zam.io-zamwallet/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.