Address Info Service API

Обзор

Для каждого поддерживаемого блокчейна доступен отдельный эндпоинт с параметрами адреса и идентификатора блокчейна (btc, ltc, bch, eth, ftm и др.). Для всех эндпоинтов указанные параметры являются обязательными.

Предоставляемые сервисом данные всегда содержат следующую обязательную информацию:

Переданный в запросе адрес;
Переданный в запросе идентификатор блокчейна;
Список балансов;
Список транзакций;
Также данные могут дополнительно содержать специфичную для некоторых блокчейнов информацию, такую как состояние активации адреса и др.

GET /api/{chain}/?address={address}

{
  requestId: string;
  data:
    {
      address: string;
      chain: string;
      balances: Array<Balance>;
      transactions: Array<Transaction>;
     ... // другие блокчейн специфичные поля
    }
}

Содержит

requestId- идентификатор запроса (строка - uuid);
data- объект с информацией;
address- адрес, по которому запрашивалась информация (строка);
chain- идентификатор блокчейна (Chain);
balances- список доступных балансов (массив объектов Balance);
transactions- список транзакций (массив объектов Transaction);
другие поля, специфичные для конкретных блокчейнов (см. описание в соответствующих разделах).

Типы данных

Chain

Строковый идентификатор из списка поддерживаемых сервисом блокчейнов.

Подробное описание см. Раздел Модели данных: Сhain.

Value

Сумма актива, объект с полями:

amount- целочисленное значение количества актива во внутреннем формате (строка);
decimals- разряд дробной части десятичной дроби для приведения amount ко внешнему формату (число).

Структура данных:

Value

{ amount: string; decimals: number; }

Asset

Информация об активе, объединяет все типы ассетов.

Структура данных: Coin | Erc20Token | StellarAsset

Подробное описание полей см. Раздел Модели данных: Asset.

Balance

Информация о балансе актива, объект с полями:

asset - информация об активе (Asset);
balance - информация о сумме актива (Value).

Структура данных:

Balance

{
  asset: Asset;
  balance: Value;
}

Transaction

Объект с полями:

txid- идентификатор/хэш транзакции (строка);
block- идентификатор блока/леджера (строка);
date- дата создания транзакции (число - дата в unix формате);
fee- комиссия в валюте коина (Value);
value- сумма в валюте коина (Value);
from- адрес отправителя (строка);
to- адрес получателя (строка);
status- статус, отражающий текущее состояние транзакции в сети (Status);
actions- список действий, совершенных в рамках этой транзакции (массив объектов Action).

Структура данных:

Transaction

{
  txid: string;
  block: string;
  date: number;
  fee: Value;
  value: Value;
  from: string;
  to: string;
  status: Status;
  actions: Array<Action>;
}

Status

Строка из списка поддерживаемых сервисом состояний транзакции, доступные значения 'pending', 'confirmed', 'rejected'.

Action

Информация о действии, совершенном в рамках транзакции, объединяет все типы действий.

type- тип действия (фиксированная строка);
asset- информация об активе (Asset);
value- сумма актива (Value);
from- адрес отправителя (строка);
to- адрес получателя (строка).

Структура данных: ActionTransfer

ActionTransfer

{
  type: 'transfer';
  asset: Asset;
  value: Value;
  from: string;
  to: string;
}

Network

Network - тип сети. Как правило, блокчейны поддерживают минимум два варианта: тестовая сеть для разработки (testnet) с фиктивными активами и стабильная рабочая сеть (livenet) с реальными активами.

Структура данных:

type Network = 'livenet' | 'testnet';

API

Биткоин и биткоин-подобные криптовалюты

Адрес сервера https://cloud.spatium.net/address-info-btc-like/v1

Swagger

Для данного адреса сервера доступен запрос информации по адресам блокчейнов btc, ltc, bch, структура информации в ответах для них одинакова.

Также есть возможность получения данных по адресам тестовых сетей btc и ltc с помощью необязательного параметра network.

Структура запроса

GET /api/{chain}/?address={address}&network=livenet

Параметры

address - адрес, обязательный параметр (строка),
network - тип сети, необязательный параметр, значение по умолчанию 'livenet' (Network).

Структура ответа

{
  requestId: string;
  data: {
    address: string;
    chain: Chain;
    balances: Array<{
      asset: Coin;
      balance: Value;
    }>;
    transactions: Array<{
      txid: string;
      block: string;
      date: number;
      fee: Value;
      value: Value;
      from: string;
      to: string;
      status: Status;
      actions: Array<{
        type: 'transfer';
        asset: Coin;
        value: Value;
        from: string;
        to: string;
      }>;
    }>;
  }
}

Пример использования

GET https://cloud.spatium.net/address-info-btc-like/v1/api/btc/?address=bc1qsrampw4569jmurj22z544d9n25cc5ut4xqmzwm

Пример ответа

{
  requestId: 'f28a1a12-0b9d-4335-8c39-5636f75569df',
  data: {
    address: 'bc1qsrampw4569jmurj22z544d9n25cc5ut4xqmzwm',
    chain: 'btc',
    balances: [{
      asset: {
        kind: 'coin',
        chain: 'btc',
      },
      balance: { amount: '114492', decimals: 8 },
    }],
    transactions: [{
      txid: '88ae5ffad07794cbb89680a2ee6f9014535b921417343ca5dec5f2fcc9ea162c',
      block: '650924',
      date: 1601644422,
      fee: { amount: '35346', decimals: 8 },
      value: { amount: '500149885', decimals: 8 },
      from: 'bc1qq904ynep5mvwpjxdlyecgeupg22dm8am6cfvgq',
      to: 'bc1qsrampw4569jmurj22z544d9n25cc5ut4xqmzwm',
      status: 'confirmed',
      actions: [{
        type: 'transfer',
        asset: {
          kind: 'coin',
          chain: 'btc',
        },
        value: { amount: '184000', decimals: 8 },
        from: 'bc1qq904ynep5mvwpjxdlyecgeupg22dm8am6cfvgq',
        to: 'bc1qsrampw4569jmurj22z544d9n25cc5ut4xqmzwm',
      }],
    }],
  },
}

Содержит

requestId- идентификатор запроса (строка - uuid);
data- объект с информацией;

Ethereum и Ethereum-подобные криптовалюты

Адрес сервера: https://cloud.spatium.net/address-info-eth-like/v1

Swagger

Для данного адреса сервера доступен запрос информации по адресам блокчейнов eth, ftm, avax, matic, bsc, arb, структура информации в ответах для них одинакова.

Структура запроса

GET /api/{chain}/?address={address}

Параметры

address - адрес, обязательный параметр (строка),
network - тип сети, необязательный параметр, значение по умолчанию 'livenet' (Network).

Структура ответа

{
  requestId: string;
  data: {
    address: string;
    chain: Chain;
    balances: Array<{
      asset: Coin | Erc20Token;
      balance: Value;
    }>;
    transactions: Array<{
      txid: string;
      block: string;
      date: number;
      fee: Value;
      value: Value;
      from: string;
      to: string;
      status: Status;
      actions: Array<{
        type: 'transfer';
        asset: Coin | Erc20Token;
        value: Value;
        from: string;
        to: string;
      }>;
    }>;
  }
}

Пример использования

GET https://cloud.spatium.net/address-info-eth-like/v1/api/eth/?address=0x38e9a6dababD958080D1fB58FB18EFF76F6701bD

Пример ответа

{
  "address": "0x38e9a6dababD958080D1fB58FB18EFF76F6701bD",
  "chain": "eth",
  "balances": [
    {
      "asset": {
        "kind": "coin",
        "chain": "eth",
      },
      "balance": { "amount": "162237914692706569", "decimals": 18 },
    },
    {
      "asset": {
        "kind": "erc20",
        "chain": "eth",
        "contract": "0x6b175474e89094c44da98b954eedeac495271d0f",
      },
      "balance": { "amount": "16182361993003567338", "decimals": 18 },
    },
    {
      "asset": {
        "kind": "erc20",
        "chain": "eth",
        "contract": "0xdac17f958d2ee523a2206206994597c13d831ec7",
      },
      "balance": { "amount": "1517335", "decimals": 6 },
    },
  ],
  "transactions": [
    {
      "txid": "0x61d507997195483b7e52f03ae53e10707a42707063a3edce8cca2b68817ace27",
      "block": "10833917",
      "date": 1599739945,
      "fee": { "amount": "2982000000000000", "decimals": 18 },
      "value": { "amount": "299500000000000000", "decimals": 18 },
      "from": "0x278a60dEA57d909CA4BD7ab750F0c1fC06AcC31e",
      "to": "0x38e9a6dababD958080D1fB58FB18EFF76F6701bD",
      "status": "confirmed",
      "actions": [
        {
          "type": "transfer",
          "asset": {
            "kind": "coin",
            "chain": "eth",
          },
          "from": "0x278a60dEA57d909CA4BD7ab750F0c1fC06AcC31e",
          "to": "0x38e9a6dababD958080D1fB58FB18EFF76F6701bD",
          "value": { "amount": "299500000000000000", "decimals": 18 }
        },
      ],
    },
    {
      "txid": "0x50f1313cd114b463d1c9b299754101af5567bf2776d00400d61c77b7a46a8cec",
      "block": "10866330",
      "date": 1600169023,
      "fee": { "amount": "11079834000000000", "decimals": 18 },
      "value": { "amount": "0", "decimals": 18 },
      "from": "0x59a5208B32e627891C389EbafC644145224006E8",
      "to": "0x6B175474E89094C44Da98b954EedeAC495271d0F",
      "status": "confirmed",
      "actions": [
        {
          "type": "transfer",
          "asset": {
            "kind": "erc20",
             "chain": "eth",
             "contract": "0x6b175474e89094c44da98b954eedeac495271d0f",
          },
          "from": "0x59a5208B32e627891C389EbafC644145224006E8",
          "to": "0x38e9a6dababD958080D1fB58FB18EFF76F6701bD",
          "value": { "amount": "49650000000000000000", "decimals": 18 },
        },
      ],
    },
    {
      "txid": "0xed3765d32e5a109bd6a467e562b9b20776987e7811ee2162f4dd31fc778f24ea",
      "block": "10950835",
      "date": 1601294273,
      "fee": { "amount": "4945080000000000", "decimals": 18 },
      "value": { "amount": "0", "decimals": 18 },
      "from": "0x403C41f66A09f2E7f9C2351BFdaad22934295E72",
      "to": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
      "status": "confirmed",
      "actions": [
        {
          "type": "transfer",
          "asset": {
            "kind": "erc20",
            "chain": "eth",
            "contract": "0xdac17f958d2ee523a2206206994597c13d831ec7",
          },
          "from": "0x403C41f66A09f2E7f9C2351BFdaad22934295E72",
          "to": "0x38e9a6dababD958080D1fB58FB18EFF76F6701bD",
          "value": { "amount": "2072530756", "decimals": 6 },
        },
      ],
    },
  ],
}

Содержит

requestId- идентификатор запроса (строка - uuid);
data- объект с информацией;

Stellar (XLM)

Адрес сервера https://cloud.spatium.net/address-info-xlm/v1

Swagger

Для данного адреса сервера доступен запрос информации по адресам блокчейна xlm.

Также есть возможность получения данных по адресам тестовой сети xlm с помощью необязательного параметра network.

Структура запроса

GET /api/{chain}/?address={address}&network=livenet

Параметры

address - адрес, обязательный параметр (строка),
network - тип сети, необязательный параметр, значение по умолчанию 'livenet' (Network).

Структура ответа

  {
    requestId: string;
    data: {
      address: string;
      chain: Chain;
      balances: Array<{
        asset: Coin | StellarAsset;
        balance: Value;
      }>;
      transactions: Array<{
        txid: string;
        block: string;
        date: number;
        fee: Value;
        value: Value;
        from: string;
        to: string;
        status: Status;
        actions: Array<{
          type: 'transfer';
          asset: Coin | StellarAsset;
          value: Value;
          from: string;
          to: string;
        } | {
          type: 'create-account';
          asset: Coin;
          value: Value;
          from: string;
          to: string;
        } | {
          type: 'change-trust';
          asset: StellarAsset;
          to: string;
        } | {
          type: 'claim-claimable-balance';
          asset: Coin | StellarAsset;
          balanceId: string;
        }>;
      }>;
      activated: boolean;
      reserves: {
        baseReserve: string;
        trustlinesCount: number;
        reservedBalance: {
          asset: Coin;
          balance: Value;
        };
      };
      claimableBalances: Array<{
        status: 'expired' | 'claimable' | 'upcoming';
        asset: Coin | StellarAsset;
        balance: Value;
        id: string;
        from?: string;
        to: string;
        conditions: {
          validFrom?: number;
          validTo?: number;
        };
      }>;
    }
  }

Пример использования

GET https://cloud.spatium.net/address-info-xlm/v1/api/xlm/?address=GDEPVGCZJFZ2TOM26LWE3AUPLUV7D6WAQRQRPJ4FPX2AWS7EV2WLNWND

Пример ответа

  {
    requestId: 'f28a1a12-0b9d-4335-8c39-5636f75569df',
    data: {
      "address": "GDEPVGCZJFZ2TOM26LWE3AUPLUV7D6WAQRQRPJ4FPX2AWS7EV2WLNWND",
      "chain": "xlm",
      "balances": [
        {
          "asset": {
            "kind": "coin",
            "chain": "xlm"
          },
          "balance": {
            "amount": "10005000",
            "decimals": 7
          }
        }
      ],
      "transactions": [
        {
          "txid": "50a3c397b637e1bcd566d952f761f06d25735af2c5ea75b872056b462d216dc4",
          "block": "45034411",
          "date": 1676901371,
          "status": "confirmed",
          "from": "GDEPVGCZJFZ2TOM26LWE3AUPLUV7D6WAQRQRPJ4FPX2AWS7EV2WLNWND",
          "to": "GDXA26BDRMCNIL63DDHHI2257UR7E3HRSDLY4LNZI6JGWEWXZBYXJKI2",
          "actions": [
            {
              "type": "create-account",
              "asset": {
                "kind": "coin",
                "chain": "xlm"
              },
              "from": "GDEPVGCZJFZ2TOM26LWE3AUPLUV7D6WAQRQRPJ4FPX2AWS7EV2WLNWND",
              "to": "GDXA26BDRMCNIL63DDHHI2257UR7E3HRSDLY4LNZI6JGWEWXZBYXJKI2",
              "value": {
                "amount": "-29988453",
                "decimals": 7
              }
            }
          ],
          "value": {
            "amount": "-29988453",
            "decimals": 7
          },
          "fee": {
            "amount": "5000",
            "decimals": 7
          }
        },
        {
          "txid": "5e2c96cc4def9f9823da17c1a3ef4970f904cc40538db1c57bf752785fd77ee1",
          "block": "44218064",
          "date": 1672211756,
          "status": "confirmed",
          "from": "GACSZNBQIFK4THN55IOSUTFBD4E2NOGARIQBYT3BV3CXXAFZCVQZBGGG",
          "to": "GDEPVGCZJFZ2TOM26LWE3AUPLUV7D6WAQRQRPJ4FPX2AWS7EV2WLNWND",
          "actions": [
            {
              "type": "transfer",
              "asset": {
                "kind": "coin",
                "chain": "xlm"
              },
              "from": "GACSZNBQIFK4THN55IOSUTFBD4E2NOGARIQBYT3BV3CXXAFZCVQZBGGG",
              "to": "GDEPVGCZJFZ2TOM26LWE3AUPLUV7D6WAQRQRPJ4FPX2AWS7EV2WLNWND",
              "value": {
                "amount": "30000000",
                "decimals": 7
              }
            }
          ],
          "value": {
            "amount": "30000000",
            "decimals": 7
          },
          "fee": {
            "amount": "100",
            "decimals": 7
          }
        },
      ],
      "activated": true,
      "reserves": {
        "baseReserve": "5000000",
        "trustlinesCount": 0,
        "reservedBalance": {
          "asset": {
            "kind": "coin",
            "chain": "xlm"
          },
          "balance": {
            "amount": "10000000",
            "decimals": 7
          }
        }
      },
      "claimableBalances": [
        {
          "status": "claimable",
          "id": "0000000005ee24b165c0b8a4a126386cf49771fa4f9a766cd3ec8b2392406bbc97ce4d4f",
          "asset": {
            "kind": "stellar-asset",
            "chain": "xlm",
            "code": "USDC",
            "issuer": "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
          },
          "from": "GAPO6T6UV4T64E5257RBUDG66ZLFWWDBOSGHHNXAIOKKBZWIHHOQQTK2",
          "to": "GDEPVGCZJFZ2TOM26LWE3AUPLUV7D6WAQRQRPJ4FPX2AWS7EV2WLNWND",
          "balance": {
            "amount": "4378971",
            "decimals": 7
          },
          "conditions": {}
        }
      ]
    },
  }

Содержит

requestId- идентификатор запроса (строка - uuid);
data- объект с информацией;