NAV
protobuf json

Introduction

Sirius is a Digital Assets custody and a blockchain infrastructure API allowing consumers to manage blockchain wallets, keep their assets safe in self-managed custody, flexibly control transaction signing policies, receive deposits and execute withdrawals leveraging omnibus model, deploy and invoke smart contracts, receive smart contract events and read smart contract storage in many different blockchains in a general manner using the same API, data models and management UI. You don't need to learn the particularities of all the blockchains to get into the crypto world and use all top blockchains with ease.

For more information about Sirius, please contact us info@swisschain.io.

Feedback

In the case, if you have found an issue in REST API, gRPC API, Universe portal, or in this documentation, please give us feedback by adding a GitHub issue. Thank you!

gRPC Protocol description

Sirius API uses gRPC protocol as the main one. To learn more about gRPC please follow grpc.io

There are several ways to use Sirius gRPC API. If you use .NET, the most convenient way for you is Sirius.Api.Client Nuget Package.

Otherwise, you can get proto files directly and generate client on almost any platform.

.NET client registration


var options = new SiriusApiOptions
{
    ServerGrpcUrl = new Uri("https://sirius-grpc.swisschain.io"),
    ApiKey = "<you api key>",
    Timeout = TimeSpan.FromSeconds(60)
};

services.AddSiriusApiClient(options);

In startup.cs file in ConfigureServices method add API client using IServiceCollection extension method AddSiriusApiClient.

Authentication

Sirius API uses Bearer authentication. Authorization token that a client needs to send with a request is a JWT token. To get the token, contact us to get invitation code, then register in our Universe portal, create a subscription and create an API key. We use JWT as the API key, so you can explore which claims particular token contains using jwt.io online service.

Authorization token should be passed as a gRPC metadata item with the key Authorization and value prefix Bearer:

name type placement description example
Authorization string metadata Sirius API key obtained via Universe portal prepended with the Bearer prefix Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJzaXJpdXMuc3dpc3NjaGFpbi5pbyIsImFwaS1rZXktaWQiOiJjM2U3NzhlNy0yM2JjLTQ3YzAtYmYxNC0wMWQ4ZGIxZjQ0YTciLCJ1bmlxdWVfbmFtZSI6IjIiLCJ0ZW5hbnQtaWQiOiJlNmY5Y2U3ZS1hZGFmLTRmNDgtYWI2ZC1lMjBiODk1YzRjZGEiLCIyZmEtZW5hYmxlZCI6IkZhbHNlIiwibmJmIjoxNjY5ODIyODI2LCJleHAiOjE2ODAyMTAwMDAsImlhdCI6MTY2OTgyMjgyNn0.04j2NB8e--mwhvXnEO5Hpd6khoh-Q5uuzT72xX06dFc

For simplicity this metadata item is not shown in every request that requires authorization.

Guid

Some API objects have string fields that in fact contain Guid. Exact format is xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx

JSON string

Although given API is a gRPC API, some gRPC objects may have string fields that contain some data serialized in the JSON format. Mainly such JSON strings are used to represent data that should be signed. Data can be serialized to JSON using any serialization options, the only requirement - JSON should follow RFC 8259

JSON string timestamp

Since timestamp representation is not fixed in the RFC 8259, given API uses textual representation following ISO 8601. Exact format is yyyy-MM-ddThh:mm:ss.ffffffZ. Timestamps are always in UTC time zone

Pagination

Sirius API uses cursor-based pagination model in all endpoints which can return loads of items.

Request


var pagination = new PaginationInt64
{
    Cursor = 10008,
    Limit = 100,
    Order = PaginationOrder.Asc
}

name type description example
cursor optional, string Cursor to continue the search stellar-test
limit optional, int Maximum number of items to return in the search results 10
order optional, Order Result items sorting order asc

Response


var items = response.Body.Items;
var pagination = response.Body.Pagination;

name type description
Items List The array of an objects
Pagination Pagination Pagination state to continue search

Models

Pagination information


var cursor = response.Body.Pagination.Cursor;
var count = response.Body.Pagination.Count;
var order = response.Body.Pagination.Order;

name type description example
Cursor optional, string Cursor to continue the search stellar-test
Count optional, number Number of items in the current page 10
Order optional, Order Result items sorting order asc

Order (enum)

Order of the sorting

REST Protocol description

It's recommended to user gRPC API but if your platform doesn't support gRPC, you can revert to the Sirius REST API.

Allowed HTTP Verbs

Description Of HTTP Server Responses

Authentication

Sirius API uses Bearer authentication. To get the token, contact us to get invitation code, then register in our Universe portal, create a subscription and create an API key. We use JWT as the API key, so you can explore which claims particular token contains using jwt.io online service.

Request Header

  "Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJzaXJpdXMuc3dpc3NjaGFpbi5pbyIsImFwaS1rZXktaWQiOiJjM2U3NzhlNy0yM2JjLTQ3YzAtYmYxNC0wMWQ4ZGIxZjQ0YTciLCJ1bmlxdWVfbmFtZSI6IjIiLCJ0ZW5hbnQtaWQiOiJlNmY5Y2U3ZS1hZGFmLTRmNDgtYWI2ZC1lMjBiODk1YzRjZGEiLCIyZmEtZW5hYmxlZCI6IkZhbHNlIiwibmJmIjoxNjY5ODIyODI2LCJleHAiOjE2ODAyMTAwMDAsImlhdCI6MTY2OTgyMjgyNn0.04j2NB8e--mwhvXnEO5Hpd6khoh-Q5uuzT72xX06dFc

Error responses

Until other is specified for the particular endpoint and HTTP status code, the error response model is:

Error response.

{
  "errors": {
    "": [
      "Errors summary"
    ],
    "order": [
      "Invalid order"
    ],
    "limit": [
      "Limit should be in the range 1..1000"
    ]
  }
}

Pagination

Sirius API uses cursor-based pagination model in all endpoints which can return loads of items.

Pagination parameters are passed via query string. The parameters can be:

The response is:

Paginated

Paginated response

Decimal number

Here you can see how decimal numbers are presented (Price, Volume, Amount, etc) in API contract.

In the Rest API, the decimal type is presented as a number with strict precision.

Decimal number example

{
    "price": 222231.33420001911,
    "volume": 0.0000001
}

Timestamp

iso 8601 is used for the timestamps in the form 2020-08-04T08:05:09.039924+00:00

Timestamp example

{
   "Timestamp": "2020-08-04T08:05:09.039924+00:00"
}

Blockchains

We distinguish Blockchain, Protocol, and Network Type.

Blockchain is not just Bitcoin or Ethereum, it's a particular network. For example Bitcoin MainNet, Ethereum Ropsten are blockchains, whilst Bitcoin and Ethereum are protocols which are used by these blockchains. Networks can be one of the types - private, test, public. So Blockchain has a protocol and network type.

Blockchain is an "instance" of the protocol - Ethereum Ropsten, Bitcoin Mainnet, Ethereum Mainnet.

Protocol is a set of rules on how blockchain nodes interact with each other - Bitcoin, Ethereum, Ripple.

Network type can be private, test, or public.

Search blockchains

Request

Rest API: GET /api/blockchains

Query Parameters

name type description example
id optional, string Exact ID of the blockchain to search bitcoin-private
name optional, string Text to search in the name of the blockchain Bitcoin private network
protocolCode optional, string Exact ode of the protocol to search bitcoin
protocolName optional, string Text to search in the name of the protocol Bitcoin
networkType optional, NetworkType List of the network types to search. Repeat the parameter to specify multiple items private
order optional, Order Result items sorting order asc
cursor optional, string Cursor to continue the search stellar-test
limit optional, number Maximum number of items to return in the search results 10

Response

Paginated array of the blockchains:

name type description example
id string Unique identifier. bitcoin-private
tenantId optional, string Id of the tenant that owns the blockchain 100000
name string Name of the blockchain bitcoin-private
networkType NetworkType Type of the network
protocol BlockchainProtocol Protocol of the blockchain.
latestBlockNumber number Number of the latest block 1567432
isDisabled booledn Is blockchain currently working false

GET /api/blockchains 200 OK

{
  "pagination": {
    "cursor": null,
    "count": 3,
    "order": "asc",
    "nextUrl": "/api/blockchains?Order=Asc&Cursor=stellar-test&Limit=3"
  },
  "items": [
    {
      "id": "bitcoin-private",
      "protocol": {
        "code": "bitcoin",
        "name": "Bitcoin",
        "startBlockNumber": 0,
        "requirements": {
          "publicKey": true
        },
        "capabilities": {
          "destinationTag": {
            "number": null,
            "text": null
          }
        },
        "doubleSpendingProtectionType": "coins"
      },
      "tenantId": null,
      "name": "Bitcoin private network",
      "networkType": "private",
      "latestBlockNumber": 5899,
      "isDisabled": false
    },
    {
      "id": "ethereum-ropsten",
      "protocol": {
        "code": "ethereum",
        "name": "Ethereum",
        "startBlockNumber": 0,
        "requirements": {
          "publicKey": false
        },
        "capabilities": {
          "destinationTag": {
            "number": null,
            "text": null
          }
        },
        "doubleSpendingProtectionType": "nonce"
      },
      "tenantId": null,
      "name": "Ethereum test network",
      "networkType": "test",
      "latestBlockNumber": 8450781,
      "isDisabled": false
    },
    {
      "id": "stellar-test",
      "protocol": {
        "code": "stellar",
        "name": "Stellar",
        "startBlockNumber": 1,
        "requirements": {
          "publicKey": false
        },
        "capabilities": {
          "destinationTag": {
            "number": {
              "min": 1,
              "max": 9223372036854776000,
              "name": "Memo ID"
            },
            "text": {
              "maxLength": 28,
              "name": "Memo text"
            }
          }
        },
        "doubleSpendingProtectionType": "nonce"
      },
      "tenantId": null,
      "name": "Stellar test network",
      "networkType": "test",
      "latestBlockNumber": 133093,
      "isDisabled": false
    }
  ]
}

Get latest block

Request

Rest API: GET /api/blockchains/{id}/latest-block

Parameters

name type description example
id string Exact ID of the blockchain to search bitcoin-private

Response

The latest block of the specified blockchain:

name type description example
blockNumber number Number of the latest block. 5933

GET /api/blockchains/{id}/latest-block 200 OK

{
  "blockNumber": 5933
}

Assets

Sirius provides the set of crypto assets available to use. You can get notifications about a deposit or initiate a withdrawal in any asset presented in this set. Each asset has a symbol, accuracy, optional address, ID of the blockchain containing this asset and unique ID. It's possible that in the different blockchains assets with the same symbol and/or address are existed, so you have to rely only on the asset ID if you need to deterministically identify it. In fact asset ID corresponds to its blockchain ID + symbol + address. If you've received a deposit of an asset which is not supported by Sirius yet, you can add this particular asset to your personal list by specifying all needed asset parameters.

Search assets

Request

Rest API: GET /api/assets

Parameters

Query Parameters

name type description example
id optional, number ID of the asset to search 100553
blockchainId optional, string Exact blockchain id to search bitcoin-private
symbol optional, string Text to search in the asset symbol BTC
address optional, string Exact address to search 0xC1701AbD559FC263829CA3917d03045F95b5224A
accuracy optional, number Exact accuracy to search 8
order optional, Order Result items sorting order asc
cursor optional, string Cursor to continue the search stellar-test
limit optional, number Maximum number of items to return in the search results 10

Response

Paginated array of the assets:

name type description example
id number ID of the asset to search 100003
blockchainId string Exact blockchain id to search bitcoin-private
symbol string Text to search in the asset symbol BTC
address optional, string Exact address to search 0xC1701AbD559FC263829CA3917d03045F95b5224A
accuracy number Exact accuracy to search 8

GET /api/assets 200 OK

{
  "pagination": {
    "cursor": null,
    "count": 3,
    "order": "asc",
    "nextUrl": "/api/assets?Symbol=BTC&Order=Asc&Cursor=100110&Limit=3"
  },
  "items": [
    {
      "id": 100003,
      "blockchainId": "ethereum-ropsten",
      "symbol": "WBTC",
      "address": "0x3DFf0dCE5fc4B367Ec91d31DE3837cf3840c8284",
      "accuracy": 8
    },
    {
      "id": 100085,
      "blockchainId": "ethereum-ropsten",
      "symbol": "sBTC",
      "address": "0xC1701AbD559FC263829CA3917d03045F95b5224A",
      "accuracy": 18
    },
    {
      "id": 100110,
      "blockchainId": "ethereum-ropsten",
      "symbol": "TBTC",
      "address": "0xa609f2c9C5B7873F353C15D4ef6e151D14db69CC",
      "accuracy": 18
    }
  ]
}

Custodies

A Custody is a place where private keys of your blockchain wallets are generated and kept, where your transaction signing policy can be edited and where it executes. In order to create any broker-account or account, receive or send transactions in Sirius, you have to create a Custody first. There are two types of the Custody:

We recommend using Shared Custody for the testing purposes only.

Custody creation

Request

Rest API: POST /api/custodies

gRPC API: swisschain.sirius.api.custodies.Custodies/Create

POST /api/custodies

> Request: (application/json)

x-request-id: 1a5c0b3d15494ec8a390fd3b22d757d6

{
  "name": "My Custody",
  "type": "private"
}
swisschain.sirius.api.custodies.Custodies/Create

> Requets: (application/grpc)

message CustodyCreateRequest {
  string request_id = 1;    // 1a5c0b3d15494ec8a390fd3b22d757d6
  string name = 2;          // "My Custody"
  CustodyType type = 3;     // CustodyType.PRIVATE
}
REST name gRPC name type REST placement description
X-Request-ID - string header Unique ID of the request
- request_id string - Unique ID of the request
name name string body Name of the custody
type type CustodyType body Type of the custody

Response

POST /api/custodies 

> Response: 200 (application/json) - success response

{
  "id": 100010,
  "name": "My Custody",
  "type": "private",
  "status": "offline",
  "createdAt": "2020-08-24T21:43:02.6554641Z",
  "updatedAt": "2020-08-24T21:43:02.6554641Z"
}
swisschain.sirius.api.custodies.Custodies/Create

> Response: (application/grpc) - success response

message CustodyCreateResponse {
    oneof result {
      CustodyCreateResponseBody body = 1;                       // Object
      swisschain.sirius.api.common.ErrorResponseBody error = 2; // NULL
    } 
}

message CustodyCreateResponseBody {
  CustodyResponse custody = 1;                                  // Object
}

message CustodyResponse {
  int64 id = 1;                                                 // 100010
  string name = 2;                                              // "My Custody"
  CustodyType type = 3;                                         // CustodyType.PRIVATE
  CustodyStatus status = 4;                                     // CustodyStatus.OFFLINE
  google.protobuf.Timestamp created_at = 5;                     // "2020-08-24T21:43:02.6554641Z"
  google.protobuf.Timestamp updated_at = 6;                     // "2020-08-24T21:43:02.6554641Z"
}
REST name gRPC name type description
id id number ID of the custody
name name string Name of the custody
type type CustodyType Type of the custody
status status CustodyStatus Status of the custody
createdAt created_at timestamp Date of the custody creation
updatedAt updated_at timestamp Date of the custody update

Custody update

Request

Rest API: PUT /api/custodies/{custodyId}

gRPC API: swisschain.sirius.api.custodies.Custodies/Update

PUT /api/custodies/100010

> Request: (application/json)

x-request-id: 1a5c0b3d15494ec8a390fd3b22d757d6

{
  "name": "My Secure Custody"
}
swisschain.sirius.api.custodies.Custodies/Update

> Requets: (application/grpc)

message CustodyUpdateRequest {
  string request_id = 1;    // 1a5c0b3d15494ec8a390fd3b22d757d6
  int64 custody_id = 2;     // 100010
  string name = 3;          // "My Secure Custody"
}
REST name gRPC name type REST placement description
X-Request-ID - string header Unique ID of the request
- request_id string - Unique ID of the request
custodyId custody_id number path ID of the custody being update
name name string body Name of the custody to set

Response

PUT /api/custodies/100010

> Response: 200 (application/json) - success response

{
  "id": 100010,
  "name": "My Secure Custody",
  "type": "private",
  "status": "offline",
  "createdAt": "2020-08-24T21:43:02.6554641Z",
  "updatedAt": "2020-08-24T21:43:02.6554641Z"
}
swisschain.sirius.api.custodies.Custodies/Update

> Response: (application/grpc) - success response

message CustodyUpdateResponse {
  oneof result {
    CustodyUpdateResponseBody body = 1;                         // Object
    swisschain.sirius.api.common.ErrorResponseBody error = 2;   // NULL
  } 
}

message CustodyUpdateResponseBody {
  CustodyResponse custody = 1;                                  // Object
}

message CustodyResponse {
  int64 id = 1;                                                 // 100010
  string name = 2;                                              // "My Secure Custody"
  CustodyType type = 3;                                         // CustodyType.PRIVATE
  CustodyStatus status = 4;                                     // CustodyStatus.OFFLINE
  google.protobuf.Timestamp created_at = 5;                     // "2020-08-24T21:43:02.6554641Z"
  google.protobuf.Timestamp updated_at = 6;                     // "2020-08-24T21:43:02.6554641Z"
}
REST name gRPC name type description
id id number ID of the custody
name name string Name of the custody
type type CustodyType Type of the custody
status status CustodyStatus Status of the custody
createdAt created_at timestamp Date of the custody creation
updatedAt updated_at timestamp Date of the custody update

Request

Rest API: GET /api/custodies

gRPC API: swisschain.sirius.api.custodies.Custodies/Search

GET /api/custodies?id=100010&name=My%20Custody&type=private&order=asc&cursor=100009&limit=3
swisschain.sirius.api.custodies.Custodies/Search

> Requets: (application/grpc)

message CustodySearchRequest {  
  google.protobuf.Int64Value id = 1;                            // 100010
  google.protobuf.StringValue name = 2;                         // "My Custody"
  repeated CustodyType type = 3;                                // Array<CustodyType>
  swisschain.sirius.api.common.PaginationInt64 pagination = 4;  // Object
}

message PaginationInt64 {
  PaginationOrder order = 1;                                    // PaginationOrder.ASC
  google.protobuf.Int64Value cursor = 2;                        // 100009
  int32 limit = 3;                                              // 3
}
REST name gRPC name type REST placement description
id id number, optional query Exact ID of the custody to search
name name string, optional query Name of the custody to search
type type Array<CustodyType>, optional query Zero or several custody types to search
order pagination.order Order, optional query Results sorting order
cursor pagination.cursor number, optional query Cursor to continue search from
limit pagination.limit number, optional query Max numbers of the items to return from the server

Response

GET /api/custodies?&name=Custody&type=private&order=asc&cursor=100009&limit=3

> Response: 200 (application/json) - success response

{
  "pagination": {
    "cursor": 100009,
    "count": 3,
    "order": "asc",
    "nextUrl": "/api/custodies?&name=Custody&type=private&order=asc&cursor=100012&limit=3"
  },
  "items": [
    {
      "id": 100010,
      "name": "My Custody",
      "type": "shared",
      "status": "online",
      "createdAt": "2020-08-27T22:08:56.976533Z",
      "updatedAt": "2020-08-27T22:08:56.976533Z"
    },
    {
      "id": 100011,
      "name": "My Secure Custody",
      "type": "private",
      "status": "online",
      "createdAt": "2020-08-27T22:08:56.976533Z",
      "updatedAt": "2020-08-27T22:08:56.976533Z"
    },
    {
      "id": 100012,
      "name": "Test Custody",
      "type": "shared",
      "status": "online",
      "createdAt": "2020-08-27T22:08:56.976533Z",
      "updatedAt": "2020-08-27T22:08:56.976533Z"
    }
  ]
}
swisschain.sirius.api.custodies.Custodies/Search

> Response: (application/grpc) - success response

message CustodySearchResponse {
  oneof result {
    CustodySearchResponseBody body = 1;                                 // Object
    swisschain.sirius.api.common.ErrorResponseBody error = 2;           // NULL
  } 
}

message CustodySearchResponseBody {
  swisschain.sirius.api.common.PaginatedInt64Response pagination = 1;   // Object
  repeated CustodyResponse items = 2;                                   // Array<Object>
}

message CustodyUpdateResponseBody {
  CustodyResponse custody = 1;                                          // Object
}

message PaginatedInt64Response {
  google.protobuf.Int64Value cursor = 1;                                // 100009
  int32 count = 2;                                                      // 3
  PaginationOrder order = 3;                                            // PaginationOrder.ASC
}

message CustodyResponse {
  int64 id = 1;                                                         // 100010
  string name = 2;                                                      // "My Secure Custody"
  CustodyType type = 3;                                                 // CustodyType.PRIVATE
  CustodyStatus status = 4;                                             // CustodyStatus.OFFLINE
  google.protobuf.Timestamp created_at = 5;                             // "2020-08-24T21:43:02.6554641Z"
  google.protobuf.Timestamp updated_at = 6;                             // "2020-08-24T21:43:02.6554641Z"
}

Paginated list of

REST name gRPC name type description
id id number ID of the custody
name name string Name of the custody
type type CustodyType Type of the custody
status status CustodyStatus Status of the custody
createdAt created_at timestamp Date of the custody creation
updatedAt updated_at timestamp Date of the custody update

Custody API key creation

Request

Rest API: POST /api/custodies/{custodyId}/api-keys

gRPC API: swisschain.sirius.api.custodies.Custodies/AddApiKey

POST /api/custodies/100010/api-keys

> Request: (application/json)

x-request-id: d5125d2d4d9445efa5414a3926ab00a7

{
  "name": "API key for my custody",
  "expiresAt": "2020-09-24T21:43:02.6554641Z"
}
swisschain.sirius.api.custodies.Custodies/AddApiKey

> Requets: (application/grpc)

message CustodyAddApiKeyRequest {
  string request_id = 1;                        // d5125d2d4d9445efa5414a3926ab00a7
  int64 custody_id = 2;                         // 100010
  string name = 3;                              // "API key for my custody"
  google.protobuf.Timestamp expires_at = 4;     // "2020-09-24T21:43:02.6554641Z"
}
REST name gRPC name type REST placement description
X-Request-ID - string header Unique ID of the request
- request_id string - Unique ID of the request
custodyId custody_id number path ID of the custody being update
name name string body Name of the custody to set
expiresAt expires_at timestamp body Date of the API key expiration

Response

POST /api/custodies/100010/api-keys

> Response: 200 (application/json) - success response

{
  "id": 100014,
  "custodyId": 100010,
  "name": "API key for my custody",
  "expiresAt": "2020-09-24T21:43:02.6554641Z",
  "issuedAt": "2020-08-24T21:43:02.6554641Z",
  "isRevoked": false
}
swisschain.sirius.api.custodies.Custodies/AddApiKey

> Response: (application/grpc) - success response

message CustodyAddApiKeyResponse {
  oneof result {
    CustodyAddApiKeyResponseBody body = 1;                          // Object
    swisschain.sirius.api.common.ErrorResponseBody error = 2;       // NULL
  } 
}

message CustodyAddApiKeyResponseBody {
  CustodyApiKeyResponse custody_api_key = 1;                        // Object
}

message CustodyApiKeyResponse {
  int64 id = 1;                                                     // 100014
  int64 custody_id = 2;                                             // 100010
  string name = 3;                                                  // "API key for my custody"
  google.protobuf.Timestamp expires_at = 4;                         // "2020-09-24T21:43:02.6554641Z"
  google.protobuf.Timestamp issued_at = 5;                          // "2020-08-24T21:43:02.6554641Z"
  bool is_revoked = 6;                                              // FALSE
}
REST name gRPC name type description
id id number ID of the custody API key
custodyId custody_id number ID of the custody
name name string Name of the custody
expiresAt expires_at timestamp Date of the API key expiration
issuedAt issued_at timestamp Date of the API key issuance
isRevoked is_revoked bool Flag indicating if the API key is revoked

Request

Rest API: GET /api/custodies/{custodyId}/api-keys

gRPC API: swisschain.sirius.api.custodies.Custodies/SearchApiKeys

GET /api/custodies/100010/api-keys?id=100014&name=API%20key%20for%20my%20custody&isRevoked=false&order=asc&cursor=100013&limit=3
swisschain.sirius.api.custodies.Custodies/SearchApiKeys

> Requets: (application/grpc)

message CustodySearchApiKeyRequest {  
  google.protobuf.Int64Value id = 1;                            // 100014
  google.protobuf.StringValue name = 2;                         // "API key for my custody"
  int64 custody_id = 4;                                         // 100010
  google.protobuf.BoolValue is_revoked = 5;                     // false
  swisschain.sirius.api.common.PaginationInt64 pagination = 6;  // Object
}

message PaginationInt64 {
  PaginationOrder order = 1;                                    // PaginationOrder.ASC
  google.protobuf.Int64Value cursor = 2;                        // 100013
  int32 limit = 3;                                              // 3
}
REST name gRPC name type REST placement description
custodyId custody_id number path Exact ID of the custody to search
id id number, optional query Exact ID of the custody API key to search
name name string, optional query Name of the custody API key to search
isRevoked is_revoked bool, optional query Flag indicating if only revoked or only not revoked custody API keys should be searched
order pagination.order Order, optional query Results sorting order
cursor pagination.cursor number, optional query Cursor to continue search from
limit pagination.limit number, optional query Max numbers of the items to return from the server

Response

GET /api/custodies/100010/api-keys?name=API%20key&isRevoked=false&order=asc&cursor=100013&limit=3

> Response: 200 (application/json) - success response

{
  "pagination": {
    "cursor": 100009,
    "count": 3,
    "order": "asc",
    "nextUrl": /api/custodies/100010/api-keys?name=API%20key&isRevoked=false&order=asc&cursor=100016&limit=3
  },
  "items": [
    {
      "id": 100014,
      "custodyId": 100010,
      "name": "API key for my custody",
      "expiresAt": "2021-09-10T20:26:22.845Z",
      "issuedAt": "2020-09-10T20:26:22.845Z",
      "isRevoked": false
    },
    {
      "id": 100015,
      "custodyId": 100010,
      "name": "Another one API key for my custody",
      "expiresAt": "2021-09-10T20:26:22.845Z",
      "issuedAt": "2020-09-10T20:26:22.845Z",
      "isRevoked": false
    },
    {
      "id": 100016,
      "custodyId": 100010,
      "name": "One more API key for my custody",
      "expiresAt": "2021-09-10T20:26:22.845Z",
      "issuedAt": "2020-09-10T20:26:22.845Z",
      "isRevoked": false
    }
  ]
}
swisschain.sirius.api.custodies.Custodies/SearchApiKeys

> Response: (application/grpc) - success response

message CustodySearchApiKeyResponse {
  oneof result {
    CustodySearchApiKeyResponseBody body = 1;                           // Object
    swisschain.sirius.api.common.ErrorResponseBody error = 2;           // NULL
  } 
}

message CustodySearchApiKeyResponseBody {
  swisschain.sirius.api.common.PaginatedInt64Response pagination = 1;   // Object
  repeated CustodyApiKeyResponse items = 2;                             // Array<Object>
}

message CustodyApiKeyResponse {
  int64 id = 1;                                                         // 100016
  int64 custody_id = 2;                                                 // 100010
  string name = 3;                                                      // "One more API key for my custody"
  google.protobuf.Timestamp expires_at = 4;                             // "2021-09-10T20:26:22.845Z"
  google.protobuf.Timestamp issued_at = 5;                              // "2020-09-10T20:26:22.845Z"
  bool is_revoked = 6;                                                  // FALSE
}

Paginated list of

REST name gRPC name type description
id id number ID of the custody API key
custodyId custody_id number ID of the custody
name name string Name of the custody API key
expiresAt expires_at timestamp Date of the API key expiration
issuedAt issued_at timestamp Date of the API key issuance
isRevoked is_revoked bool Flag indicating if the custody API key is revoked

Custody API key token obtaining

Request

Rest API: GET /api/custodies/{custodyId}/api-keys/{apiKeyId}/token

Parameters

Query Parameters

Response

GET /api/custodies/{custodyId}/api-keys/{apiKeyId}/token 200 OK

{
}

Custody API key token revocation

Request

Rest API: POST /api/custodies/{custodyId}/api-keys/{apiKeyId}/revoke

Parameters

Query Parameters

Response

POST /api/custodies/{custodyId}/api-keys/{apiKeyId}/revoke 200 OK

{
}

Broker accounts

Broker account is the multi-currency (multi-blockchain) account which can contain unlimited number of personalized accounts within it. Broker account aggregates funds deposited to the personalized accounts and it provides funds for the withdrawals. The private keys of the broker accounts are stored in the vault associated with the broker account. The vault can't be changed once broker account is created.

You can choose which particular blockchain should be enabled for the given broker account. You can give a name to the broker account which make sense for you. It's convenient to have separate broker account for each business case. It's also reasonable to keep funds on the different brokerage accounts because of security reasons. For instance you can have a "Hot" broker account for operational work, "Cold" broker account to keep reserve funds which can be used by the limited employees group of your company, and "Frozen" broker account which can be used only by the owners of the business. Then you can setup a process to settle funds between these broker accounts on a periodical basis or on a demand.

Under the hood a broker account manages set of blockchain addresses. It has at least one address for each blockchain enabled for it. Depending on a particularities of each blockchain separate address or unique destination tag is created for each account within the broker account. Deposits received on an address of an account automatically moved to the address of the broker account. For some assets it's needed to pay fees in a different asset to move funds from an account to the broker account. For this Sirius provides "fees assets" on the account address by moving them from the broker account address.

Broker account structure:

Broker account structure lifecycle

Create a broker account

Request

Rest API: POST /api/broker-accounts

gRPC API: swisschain.sirius.api.brokerAccounts.BrokerAccounts.Create

POST /api/broker-accounts

> Request: (application/json)

x-request-id: 1a5c0b3d15494ec8a390fd3b22d757d6

{
    "amlConnectionIds": [ 600000012 ],
    "blockchainIds": [ "bitcoin-test", "ethereum-ropsten"],
    "custodyId": 404000009,
    "name": "Broker Account Name"
}
swisschain.sirius.api.brokerAccounts.BrokerAccounts.Create

> Requets: (application/grpc)

message BrokerAccountCreateRequest {
  string request_id = 1;                    // 1a5c0b3d15494ec8a390fd3b22d757d6
  string name = 2;                          // "Broker Account Name"
  int64 custody_id = 3;                     // 404000009
  repeated string blockchain_ids = 4;       // [ "bitcoin-test", "ethereum-ropsten"] Array of blockchain ids
  repeated int64 aml_connection_ids = 5;    // [ 600000012 ] Array of aml connections ids
}
REST name gRPC name type REST placement description
X-Request-ID - string header Unique ID of the request
- request_id string - Unique ID of the request
name name string body Name of the created Broker Account
custodyId custody_id number body ID of the custody for broker account
blockchainIds blockchain_ids Array of strings body Ids of the blockchains with which broker Account should work
amlConnectionIds aml_connection_ids Array of strings body Ids of the AML connections to enable for deposit/withdrawal checks

Response

POST /api/broker-accounts 

> Response: 200 (application/json) - success response

{
    "name":"Broker Account Name",
    "id":100000115,
    "state":"creating",
    "accountCount":0,
    "blockchainsCount":2,"
    createdAt":"2021-03-30T09:02:44.7726151+00:00",
    "updatedAt":"2021-03-30T09:02:44.7726151+00:00",
    "custodyId":404000009,
    "custodyName":"NewSharedHSM",
    "blockchainIds":["bitcoin-test","ethereum-ropsten"],
    "amlConnectionIds":[600000012]
}
swisschain.sirius.api.brokerAccounts.BrokerAccounts.Create

> Response: (application/grpc) - success response

message BrokerAccountCreateResponse {
    oneof result {
      BrokerAccountCreateResponseBody body = 1;                 // Object
      swisschain.sirius.api.common.ErrorResponseBody error = 2; // Object
    } 
}

message BrokerAccountCreateResponseBody {
  BrokerAccountResponse broker_account = 1;                     // Object
}

message BrokerAccountResponse {
  string name = 1;                                              // "Broker Account Name"
  int64 id = 2;                                                 // 100000115
  BrokerAccountState state = 3;                                 // BrokerAccountState.Creating
  int64 accounts_count = 4;                                     // 0
  int64 blockchains_count = 5;                                  // 2
  google.protobuf.Timestamp created_at = 6;                     // "2021-03-30T09:02:44.7726151+00:00"
  google.protobuf.Timestamp updated_at = 7;                     // "2021-03-30T09:02:44.7726151+00:00"
  int64 custody_id = 8;                                         // 404000009
  string custody_name = 9;                                      // "NewSharedHSM"
  repeated string blockchain_ids = 10;                          // ["bitcoin-test","ethereum-ropsten"]
  repeated int64 aml_connection_ids = 11;                       // [600000012]
}
REST name gRPC name type description
id id number ID of the broker account
name name string body
accountsCount accounts_count number Number of accounts that are attached to the broker account
blockchainsCount blockchains_count number Number of already created broker account details
state state BrokerAccountState Status of the broker account
createdAt created_at timestamp Date of the broker account creation
updatedAt updated_at timestamp Date of the latest broker account update
custodyId custody_id number body
custodyName custody_name string body
blockchain_ids blockchain_ids Array of string body
amlConnectionIds aml_connection_ids Array of numbers body

Update the broker account

Request

Rest API: PUT /api/broker-accounts

gRPC API: swisschain.sirius.api.brokerAccounts.BrokerAccounts.Update

PUT /api/broker-accounts

> Request: (application/json)

x-request-id: 1a5c0b3d15494ec8a390fd3b22d757d6

{
    "amlConnectionIds": [600000007, 600000012],
    "blockchainIds": ["stellar-test"],
    "brokerAccountId": 100000116
}
swisschain.sirius.api.brokerAccounts.BrokerAccounts.Update

> Requets: (application/grpc)

message BrokerAccountUpdateRequest {
  string request_id = 1;                    // 1a5c0b3d15494ec8a390fd3b22d757d6
  int64 broker_account_id = 2;              // 100000116 
  repeated string blockchain_ids = 3;       // ["stellar-test"] only new ids could be added
  repeated int64 aml_connections_ids = 4;   // [600000007, 600000012] already existing ids could be removed
}
REST name gRPC name type REST placement description
X-Request-ID - string header Unique ID of the request
- request_id string - Unique ID of the request
brokerAccountId broker_account_id number body ID of the broker account
blockchainIds blockchain_ids Array of strings body Ids of the blockchains to add to the broker account
amlConnectionIds aml_connection_ids Array of strings body Ids of the AML connections to enable for deposit/withdrawal checks

Response

PUT /api/broker-accounts 

> Response: 200 (application/json) - success response

{
    "name":"Broker Account Docs",
    "id":100000116,
    "state": "updating",
    "accountCount":0,
    "blockchainsCount":3,
    "createdAt":"2021-03-30T09:49:47.298466+00:00",
    "updatedAt":"2021-03-30T09:51:54.3471023+00:00",
    "custodyId":404000008,
    "custodyName": "SharedHSM_MAIN",
    "blockchainIds": ["bitcoin-test","ethereum-ropsten","stellar-test"],
    "amlConnectionIds":[600000007,600000012]
}
swisschain.sirius.api.brokerAccounts.BrokerAccounts.Update

> Response: (application/grpc) - success response

message BrokerAccountUpdateResponse {
  oneof result {
    BrokerAccountUpdateActionResponseBody body = 1;             // Object
    swisschain.sirius.api.common.ErrorResponseBody error = 2;   // Object
  } 
}

message BrokerAccountUpdateActionResponseBody {
  BrokerAccountResponse broker_account = 1;                     // Object
}

message BrokerAccountResponse {
  string name = 1;                                              // "Broker Account Name"
  int64 id = 2;                                                 // 100000115
  BrokerAccountState state = 3;                                 // BrokerAccountState.Creating
  int64 accounts_count = 4;                                     // 0
  int64 blockchains_count = 5;                                  // 2
  google.protobuf.Timestamp created_at = 6;                     // "2021-03-30T09:02:44.7726151+00:00"
  google.protobuf.Timestamp updated_at = 7;                     // "2021-03-30T09:02:44.7726151+00:00"
  int64 custody_id = 8;                                         // 404000009
  string custody_name = 9;                                      // "NewSharedHSM"
  repeated string blockchain_ids = 10;                          // ["bitcoin-test","ethereum-ropsten"]
  repeated int64 aml_connection_ids = 11;                       // [600000012]
}
REST name gRPC name type description
id id number ID of the broker account
name name string body
accountsCount accounts_count number Number of accounts that are attached to the broker account
blockchainsCount blockchains_count number Number of already created broker account details
state state BrokerAccountState Status of the broker account
createdAt created_at timestamp Date of the broker account creation
updatedAt updated_at timestamp Date of the latest broker account update
custodyId custody_id number body
custodyName custody_name string body
blockchain_ids blockchain_ids Array of string body
amlConnectionIds aml_connection_ids Array of numbers body

Searches broker accounts

Request

Rest API: GET /api/broker-accounts

gRPC API: swisschain.sirius.api.brokerAccounts.BrokerAccounts.Search

Query Parameters

REST name gRPC name type description example
id id optional, number Exact broker account ID to search 100000113
name name optional, string Name of the broker account Broker account name
state state optional, Array of BrokerAccountState State of the broker account creating
- custody_id optional, number Find broker accounts with specified Custody ID 200000000
order pagination.order optional, Order Result items sorting order asc
cursor pagination.cursor optional, string Cursor to continue the search 11111110
limit pagination.limit optional, number Maximum number of items to return in the search results 10
swisschain.sirius.api.brokerAccounts.BrokerAccounts.Search

> Requets: (application/grpc)

message BrokerAccountSearchRequest {
  google.protobuf.Int64Value id = 1;
  google.protobuf.StringValue name = 2;
  google.protobuf.Int64Value custody_id = 3;
  repeated BrokerAccountState state = 4;
  swisschain.sirius.api.common.PaginationInt64 pagination = 5;
}

Response

GET /api/broker-accounts

> Response: 200 (application/json) - success response

{
    "pagination":
    {
        "cursor":null,
        "count":10,
        "order":"asc",
        "nextUrl":"/api/broker-accounts?Order=Asc&Cursor=100000012&Limit=10"
    },
    "items":[
        {
            "name":"first",
            "id":100000000,
            "state":"creating",
            "accountCount":1,
            "blockchainsCount":5,
            "createdAt":"2020-09-08T13:10:24.949289+00:00",
            "updatedAt":"2020-09-08T13:10:24.949289+00:00",
            "custodyId":100000,
            "custodyName":"Shared1",
            "blockchainIds":["ethereum-ropsten","bitcoin-test","stellar-test","bitcoin-private","litecoin-private"],
            "amlConnectionIds":[]
        }, ...]
}
swisschain.sirius.api.brokerAccounts.BrokerAccounts.Search

> Response: (application/grpc) - success response

message BrokerAccountSearchResponse {
  oneof result {
    BrokerAccountSearchResponseBody body = 1;                   // Object
    swisschain.sirius.api.common.ErrorResponseBody error = 2;   // Object
  } 
}

message BrokerAccountSearchResponseBody {
  swisschain.sirius.api.common.PaginatedInt64Response pagination = 1;   // Object
  repeated BrokerAccountResponse items = 2;                             // Object
}

message BrokerAccountResponse {
  string name = 1;                                              // "Broker Account Name"
  int64 id = 2;                                                 // 100000115
  BrokerAccountState state = 3;                                 // BrokerAccountState.Creating
  int64 accounts_count = 4;                                     // 0
  int64 blockchains_count = 5;                                  // 2
  google.protobuf.Timestamp created_at = 6;                     // "2021-03-30T09:02:44.7726151+00:00"
  google.protobuf.Timestamp updated_at = 7;                     // "2021-03-30T09:02:44.7726151+00:00"
  int64 custody_id = 8;                                         // 404000009
  string custody_name = 9;                                      // "NewSharedHSM"
  repeated string blockchain_ids = 10;                          // ["bitcoin-test","ethereum-ropsten"]
  repeated int64 aml_connection_ids = 11;                       // [600000012]
}

Paginated response of the broker accounts:

REST name gRPC name type description
id id number ID of the broker account
name name string body Broker account name
accountsCount accounts_count number Number of accounts that are attached to the broker account
blockchainsCount blockchains_count number Number of already created broker account details
state state BrokerAccountState Status of the broker account
createdAt created_at timestamp Date of the broker account creation
updatedAt updated_at timestamp Date of the latest broker account update
custodyId custody_id number body ID of the custody for broker account
custodyName custody_name string body Name of the custody related to broker account
blockchain_ids blockchain_ids Array of string body Blockchains ids that are connected to the broker account
amlConnectionIds aml_connection_ids Array of numbers body AML Connections that are enabled for the broker account

Searches the broker account balances

Request

Rest API: GET /api/broker-accounts/{brokerAccountId}/balances

gRPC API: swisschain.sirius.api.brokerAccounts.BrokerAccounts.GetBalances

Query Parameters

REST name gRPC name type description example
brokerAccountId broker_account_id number Find balances for specified broker account ID 200000000
assetId asset_id optional, number Show balance for specified asset ID 100000113
order pagination.order optional, Order Result items sorting order asc
cursor pagination.cursor optional, string Cursor to continue the search 11111110
limit pagination.limit optional, number Maximum number of items to return in the search results 10
swisschain.sirius.api.brokerAccounts.BrokerAccounts.GetBalances

> Requets: (application/grpc)

message BrokerAccountGetBalancesRequest {
  int64 broker_account_id = 1;                                  // 200000000
  google.protobuf.Int64Value assetId = 2;                       // 100000113
  swisschain.sirius.api.common.PaginationInt64 pagination = 3;  // Object
}

Response

GET /api/broker-accounts/{brokerAccountId}/balances

> Response: 200 (application/json) - success response

{
    "pagination":
    {
        "cursor":null,
        "count":3,
        "order":"asc",
        "nextUrl":null
    },
    "items":[
        {
            "id":102000850,
            "brokerAccountId":100000113,
            "assetId":100000,
            "ownedBalance":0.17770416,
            "availableBalance":0.17770416,
            "pendingBalance":0.0,
            "reservedBalance":0.0,
            "createdAt":"2021-03-11T13:46:09.615581+00:00",
            "updatedAt":"2021-03-19T08:53:50.020425+00:00",
            "assetSymbol":"BTC",
            "assetAddress":null,
            "blockchainName":"Bitcoin private network"
        }
        , ...]
}
swisschain.sirius.api.brokerAccounts.BrokerAccounts.GetBalances

> Response: (application/grpc) - success response

message BrokerAccountGetBalancesResponse {
  oneof result {
    BrokerAccountGetBalancesResponseBody body = 1;                      // Object
    swisschain.sirius.api.common.ErrorResponseBody error = 2;           // Object
  } 
}

message BrokerAccountGetBalancesResponseBody {
  swisschain.sirius.api.common.PaginatedInt64Response pagination = 1;   // Object
  repeated BrokerAccountBalancesResponse items = 2;                     // Paginated balances
}

message BrokerAccountBalancesResponse
{
  int64 id = 1;                                                         // 102000850
  int64 broker_account_id = 2;                                          // 100000113
  int64 asset_id = 3;                                                   // 100000
  swisschain.sirius.api.common.BigDecimal owned_balance = 4;            // 0.17770416
  swisschain.sirius.api.common.BigDecimal available_balance = 5;        // 0.17770416
  swisschain.sirius.api.common.BigDecimal pending_balance = 6;          // 0
  swisschain.sirius.api.common.BigDecimal reserved_balance = 7;         // 0
  google.protobuf.Timestamp created_at = 8;                             // "2021-03-11T13:46:09.615581+00:00"
  google.protobuf.Timestamp updated_at = 9;                             // "2021-03-19T08:53:50.020425+00:00"
  string asset_symbol = 10;                                             // "BTC"
  google.protobuf.StringValue asset_address = 11;                       // null
  string blockchain_name = 12;                                          // "Bitcoin private network"
}

Paginated response of the broker account balances:

REST name gRPC name type description
id id number ID of the broker account balance
brokerAccountId broker_account_id number ID of the broker account
assetId asset_id number ID of the asset
ownedBalance owned_balance decimal Owned balance. (see balance diagram)
availableBalance available_balance decimal Available balance. (see balance diagram)
pendingBalance pending_balance decimal Pending balance. (see balance diagram)
reservedBalance reserved_balance decimal Reserved balance. (see balance diagram)
createdAt created_at timestamp Date of the broker account balance creation
updatedAt updated_at timestamp Date of the latest broker account balance update
assetSymbol asset_symbol string Symbol of the asset
assetAddress asset_address string Asset's address on the blockchain(e.x:for tokens)
custodyName custody_name string body Name of the custody related to broker account
blockchain_name blockchain_name string body Blockchains name

Searches the broker account details

Request

Rest API: GET /api/broker-accounts/{brokerAccountId}/details

gRPC API: swisschain.sirius.api.brokerAccounts.BrokerAccounts.SearchDetails

Query Parameters

REST name gRPC name type description example
brokerAccountId broker_account_id number Find details for specified broker account ID 200000000
id id optional, number Find details for specified broker account ID 200000001
assetId asset_id optional, number Show details for specified asset ID 100000
blockchainId blockchain_id optional, number Show details for specified blockchain ID ethereum-ropsten
address address optional, number Show details for specified address 0x678401cf8200967a3998d1480512b3f9e79f9447
order pagination.order optional, Order Result items sorting order asc
cursor pagination.cursor optional, string Cursor to continue the search 11111110
limit pagination.limit optional, number Maximum number of items to return in the search results 10
swisschain.sirius.api.brokerAccounts.BrokerAccounts.SearchDetails

> Requets: (application/grpc)

message BrokerAccountDetailsSearchRequest {
  int64 broker_account_id = 1;                                  // 200000000
  google.protobuf.Int64Value id = 2;                            // 200000001
  google.protobuf.Int64Value assetId = 3;                       // 100000
  google.protobuf.StringValue blockchainId = 4;                 // "ethereum-ropsten"
  google.protobuf.StringValue address = 5;                      // "0x678401cf8200967a3998d1480512b3f9e79f9447"
  swisschain.sirius.api.common.PaginationInt64 pagination = 6;  // Pagination object
}

Response

GET /api/broker-accounts/{brokerAccountId}/details

> Response: 200 (application/json) - success response

{
    "pagination": {
        "cursor":null,
        "count":2,
        "order":"asc",
        "nextUrl":null
        },
        "items":[
            {
                "id":101000254,
                "brokerAccountId":100000113,
                "createdAt":"2021-03-10T12:27:44.666695+00:00",
                "address":"0x02d45A855dB2dD98899cdA9a58c16E8f4A1faA96",
                "blockchainId":"ethereum-ropsten"
            }, ...]
}
swisschain.sirius.api.brokerAccounts.BrokerAccounts.SearchDetails

> Response: (application/grpc) - success response

message BrokerAccountDetailsSearchResponse {
  oneof result {
    BrokerAccountDetailsSearchResponseBody body = 1;                    // Object
    swisschain.sirius.api.common.ErrorResponseBody error = 2;           // Object
  } 
}

message BrokerAccountDetailsSearchResponseBody {
  swisschain.sirius.api.common.PaginatedInt64Response pagination = 1;   // Object
  repeated BrokerAccountDetailsResponse items = 2;                      // Object
}

message BrokerAccountDetailsResponse {
  int64 id = 1;                                                         // 101000254
  int64 broker_account_id = 2;                                          // 100000113
  google.protobuf.Timestamp created_at = 3;                             // "2021-03-10T12:27:44.666695+00:00"
  string address = 4;                                                   // "0x02d45A855dB2dD98899cdA9a58c16E8f4A1faA96"
  string blockchain_id = 5;                                             // "ethereum-ropsten"
}

Paginated response of the broker account details:

REST name gRPC name type description
id id number ID of the broker account balance
brokerAccountId broker_account_id number ID of the broker account
assetId asset_id number ID of the asset
createdAt created_at timestamp Date of the broker account balance creation
address address string Asset's address on the blockchain(e.x:for tokens)
custodyName custody_name string body Name of the custody related to broker account
blockchainId blockchain_id string body Blockchain ID

Gets the broker account details by the asset id

Request

Rest API: GET /api/broker-accounts/{brokerAccountId}/details/by-asset-id/{assetId}

gRPC API: swisschain.sirius.api.brokerAccounts.BrokerAccounts.BrokerAccounts.GetDetails

Query Parameters

REST name gRPC name type description example
brokerAccountId broker_account_id number Find details for specified broker account ID 200000000
assetId asset_id number Show details for specified asset ID 100000
swisschain.sirius.api.brokerAccount.BrokerAccounts.GetDetails

> Requets: (application/grpc)

message BrokerAccountGetDetailsRequest {
  int64 brokerAccountId = 1;                        
  int64 assetId = 2;
}

Response

GET /api/broker-accounts/{brokerAccountId}/details/by-asset-id/{assetId}

> Response: 200 (application/json) - success response

{
    "id":101000254,
    "brokerAccountId":100000113,
    "createdAt":"2021-03-10T12:27:44.666695+00:00",
    "address":"0x02d45A855dB2dD98899cdA9a58c16E8f4A1faA96",
    "blockchainId":"ethereum-ropsten"
}
swisschain.sirius.api.brokerAccounts.BrokerAccounts.GetDetails

> Response: (application/grpc) - success response

message BrokerAccountGetDetailsResponse {
  oneof result {
    BrokerAccountGetDetailsResponseBody body = 1;                       // Object
    swisschain.sirius.api.common.ErrorResponseBody error = 2;           // Object
  } 
}

message BrokerAccountGetDetailsResponseBody {
  BrokerAccountDetailsResponse broker_account_details = 1;              // Object
}

message BrokerAccountDetailsResponse {
  int64 id = 1;                                                         // 101000254
  int64 broker_account_id = 2;                                          // 100000113
  google.protobuf.Timestamp created_at = 3;                             // "2021-03-10T12:27:44.666695+00:00"
  string address = 4;                                                   // "0x02d45A855dB2dD98899cdA9a58c16E8f4A1faA96"
  string blockchain_id = 5;                                             // "ethereum-ropsten"
}
REST name gRPC name type description
id id number ID of the broker account balance
brokerAccountId broker_account_id number ID of the broker account
assetId asset_id number ID of the asset
createdAt created_at timestamp Date of the broker account balance creation
address address string Asset's address on the blockchain(e.x:for tokens)
custodyName custody_name string body Name of the custody related to broker account
blockchainId blockchain_id string body Blockchain ID

Search for broker account updates

Request

gRPC API: swisschain.sirius.api.brokerAccounts.BrokerAccounts.GetUpdates

Parameters

REST name gRPC name type description example
- custody_id optional, number Search for broker accounts with this custody ID 100000113
- broker_account_id optional, number Exact broker account ID to search details for 103000113
- name optional, string Broker account name user reference
- state optional, Array of BrokerAccountState State of the account creating
- pagination.cursor optional, string Cursor to continue the search 11111110
swisschain.sirius.api.accounts.BrokerAccounts.GetUpdates

> Requets: (application/grpc)

message BrokerAccountUpdateSearchRequest {
  google.protobuf.Int64Value broker_account_id = 1;
  google.protobuf.StringValue name = 2;
  google.protobuf.Int64Value custody_id = 3;
  repeated BrokerAccountState state = 4;
  google.protobuf.Int64Value cursor = 5;
}

Response

swisschain.sirius.api.accounts.BrokerAccounts.GetUpdates

> Response: (application/grpc) - success response

message BrokerAccountUpdateArrayResponse{
  repeated BrokerAccountUpdateItemResponse items = 1;
}

message BrokerAccountUpdateItemResponse {
  string name = 1;
  int64 broker_account_id = 2;
  BrokerAccountState state = 3;
  google.protobuf.Timestamp created_at = 4;
  google.protobuf.Timestamp updated_at = 5;
  int64 custody_id = 6;
  google.protobuf.StringValue custody_name = 7;
  repeated string blockchain_ids = 8;
  int64 broker_account_update_id = 9;
}

Response is the stream of historical broker account updates and real time updates as well:

REST name gRPC name type description
- id number ID of the broker account
- name string body
- accounts_count number Number of accounts that are attached to the broker account
- blockchains_count number Number of already created broker account details
- state BrokerAccountState Status of the broker account
- created_at timestamp Date of the broker account creation
- updated_at timestamp Date of the latest broker account update
- custody_id number body
- custody_name string body
- blockchain_ids Array of string body
- aml_connection_ids Array of numbers body
- broker_account_update_id number body

Accounts

Account is the multi-currency (multi-blockchain) account which is associated with a particular broker account. Account has the same blockchains enabled as the parent broker account has. Account can be associated with a thing in your system by using the "reference ID". You can pass ID of your end-user, invoice, contract or any other things with which you want to associate deposits received on the account. Reference ID is optional, so you can avoid passing your internal IDs to Sirius and keep mapping between your objects and Sirius accounts on your side.

Create an account

Request

Rest API: POST /api/accounts

gRPC API: swisschain.sirius.api.accounts.Accounts.Create

POST /api/accounts

> Request: (application/json)

x-request-id: 1a5c0b3d15494ec8a390fd3b22d757d6

{
    "brokerAccountId": 100000113
    "referenceId": "user reference"
    "userId": 108000004
}
swisschain.sirius.api.accounts.Accounts.Create

> Requets: (application/grpc)

message AccountCreateRequest {
  string request_id = 1;                        //1a5c0b3d15494ec8a390fd3b22d757d6

  int64 broker_account_id = 2;                  //100000113

  google.protobuf.StringValue reference_id = 3; //user reference (could be empty)

  google.protobuf.Int64Value user_id = 4;       //108000004 (could be empty)
}
REST name gRPC name type REST placement description
X-Request-ID - string header Unique ID of the request
- request_id string - Unique ID of the request
brokerAccountId broker_account_id optional, number body Id of the related Broker Account
referenceId reference_id optional, string body Account reference id
userId user_id optional, number body Id of the related user in the system (Needed for enabling AML on broker Account)

Response

POST /api/accounts 

> Response: 200 (application/json) - success response

{
    "id":103000158,
    "referenceId":"user reference",
    "brokerAccountId":100000113,
    "state":"creating",
    "createdAt":"2021-03-26T14:14:46.089822+00:00",
    "updatedAt":"2021-03-26T14:14:46.089822+00:00",
    "userId":108000004,
    "userNativeId":"chainalysis-user-1"
}
swisschain.sirius.api.accounts.Accounts.Create

> Response: (application/grpc) - success response

message AccountCreateResponse {
    oneof result {
      AccountCreateResponseBody body = 1;                         // Object
      swisschain.sirius.api.common.ErrorResponseBody error = 2;   // NULL
    } 
}

message AccountCreateResponseBody {
  AccountResponse account = 1;                                      // Object
}

message AccountResponse {
  int64 id = 1;                                                     // 103000158
  string reference_id = 2;                                          // "user reference" 
  int64 broker_account_id = 3;                                      // 100000113
  AccountStateModel state = 4;                                      // AccountStateModel.Creating
  google.protobuf.Timestamp createdAt = 5;                          // "2021-03-26T14:14:46.089822+00:00"
  google.protobuf.Timestamp updatedAt = 6;                          // "2021-03-26T14:14:46.089822+00:00"
  google.protobuf.Int64Value user_id = 7;                           // 108000004
  google.protobuf.StringValue user_native_id = 8;                   // "chainalysis-user-1"
}
REST name gRPC name type description
id id number ID of the account
referenceId reference_id optional, string body
brokerAccountId broker_account_id number body
state state AccountState Status of the account
createdAt created_at timestamp Date of the account creation
updatedAt updated_at timestamp Date of the latest account update
userId user_id optional, number body
userNativeId user_native_id optional, string body

Update an account

Request

Rest API: PUT /api/accounts

gRPC API: swisschain.sirius.api.accounts.Accounts.Update

POST /api/accounts

> Request: (application/json)

x-request-id: 1a5c0b3d15494ec8a390fd3b22d757d6

{
    "accountId": 100000113
    "userId": 108000004
}
REST name gRPC name type REST placement description
X-Request-ID - string header Unique ID of the request
accountId - optional, number body Id of the related Account
userId - optional, number body Id of the related user in the system (Needed for enabling AML on broker Account)

Response

POST /api/accounts 

> Response: 200 (application/json) - success response

{
    "id":103000158,
    "referenceId":"user reference",
    "brokerAccountId":100000113,
    "state":"creating",
    "createdAt":"2021-03-26T14:14:46.089822+00:00",
    "updatedAt":"2021-03-26T14:14:46.089822+00:00",
    "userId":108000004,
    "userNativeId":"chainalysis-user-1"
}
REST name gRPC name type description
id id number ID of the account
referenceId reference_id optional, string body
brokerAccountId broker_account_id number body
state state AccountState Status of the account
createdAt created_at timestamp Date of the account creation
updatedAt updated_at timestamp Date of the latest account update
userId user_id optional, number body
userNativeId user_native_id optional, string body

Search for accounts

Request

Rest API: GET /api/accounts

gRPC API: swisschain.sirius.api.accounts.Accounts.Search

Query Parameters

REST name gRPC name type description example
id id optional, number ID of the account to search 11111111
brokerAccountId broker_account_id optional, number Exact broker account id to search 100000113
userId user_id optional, number ID of users 108000004
referenceId reference_id optional, string Account reference id user reference
state state optional, AccountState State of the account creating
order pagination.order optional, Order Result items sorting order asc
cursor pagination.cursor optional, string Cursor to continue the search 11111110
limit pagination.limit optional, number Maximum number of items to return in the search results 10
swisschain.sirius.api.accounts.Accounts.Search

> Requets: (application/grpc)

message AccountSearchRequest {
  google.protobuf.Int64Value id = 1;                            // 11111111
  google.protobuf.Int64Value broker_account_id = 2;             // 100000113
  repeated AccountStateModel state = 3;                         // [AccountStateModel.Creating, AccountStateModel.Active, AccountStateModel.Blocked]
  google.protobuf.StringValue reference_id = 4;                 // user reference
  swisschain.sirius.api.common.PaginationInt64 pagination = 5;  // Pagination object
  google.protobuf.Int64Value user_id = 6;                       //108000004 (could be empty)
}

Response

GET /api/accounts?id=103000022

> Response: 200 (application/json) - success response

{
    "pagination":
    {
        "cursor":103000021,
        "count":10,
        "order":"asc",
        "nextUrl":"/api/accounts/details?Order=Asc&Cursor=103000031&Limit=10"
    },
    "items":[
        {
            "id":103000022,
            "referenceId":"some ref7",
            "brokerAccountId":100000019,
            "state":"active",
            "createdAt":"2020-09-14T16:25:54.831938+00:00",
            "updatedAt":"2020-09-14T16:28:14.536684+00:00",
            "userId":null,
            "userNativeId":null}, ...]
}
swisschain.sirius.api.accounts.Accounts.Search

> Response: (application/grpc) - success response

message AccountSearchResponse {
    oneof result {
      AccountSearchResponseBody body = 1;                         // Object
      swisschain.sirius.api.common.ErrorResponseBody error = 2;   // NULL
    } 
}

message AccountSearchResponseBody {
  swisschain.sirius.api.common.PaginatedInt64Response pagination = 1;   // Pagination

  repeated AccountResponse items = 2;                                   // Array of objects
}

message AccountResponse {
  int64 id = 1;                                                     // 103000158
  string reference_id = 2;                                          // "user reference" 
  int64 broker_account_id = 3;                                      // 100000113
  AccountStateModel state = 4;                                      // AccountStateModel.Creating
  google.protobuf.Timestamp createdAt = 5;                          // "2021-03-26T14:14:46.089822+00:00"
  google.protobuf.Timestamp updatedAt = 6;                          // "2021-03-26T14:14:46.089822+00:00"
  google.protobuf.Int64Value user_id = 7;                           // 108000004
  google.protobuf.StringValue user_native_id = 8;                   // "chainalysis-user-1"
}

Paginated response of the accounts:

REST name gRPC name type description
id id number ID of the account
referenceId reference_id optional, string Account reference id
brokerAccountId broker_account_id number Id of the related Broker Account
status status AccountState Status of the account
createdAt created_at timestamp Date of the account creation
updatedAt updated_at timestamp Date of the latest account update
userId user_id optional, number Id of the related user in the system (Needed for enabling AML on broker Account)
userNativeId user_native_id optional, string Native Id of the user in customer's system

Searches the account details

Request

Rest API: GET /api/accounts/details

gRPC API: swisschain.sirius.api.accounts.Accounts.SearchDetails

Query Parameters

REST name gRPC name type description example
id id optional, number ID of the account details to search 11111111
accountId account_id optional, number Exact account id to search 103000000
referenceId reference_id optional, string Account reference id account reference
brokerAccountId broker_account_id optional, number Exact broker account id to search 103000113
assetId asset_id optional, number ID of an asset 108000004
blockchainId blockchain_id optional, number ID of the blockchain bitcoin-private
address address optional, string Address of the account details bcrt1qnqx8ltjez3jak8f859y20darrhawa8rq73pank
tag tag optional, string related tag null
tag_type tag_type optional, TagType tag type null
order pagination.order optional, Order Result items sorting order asc
cursor pagination.cursor optional, string Cursor to continue the search 11111110
limit pagination.limit optional, number Maximum number of items to return in the search results 10
swisschain.sirius.api.accounts.Accounts.SearchDetails

> Requets: (application/grpc)

message AccountDetailsSearchRequest {
  google.protobuf.Int64Value id = 1;                                    // 11111111
  google.protobuf.Int64Value broker_account_id = 2;                     // 103000113
  google.protobuf.Int64Value account_id = 3;                            // 103000000
  google.protobuf.StringValue reference_id = 4;                         // account reference
  google.protobuf.Int64Value asset_id = 5;                              // 108000004
  google.protobuf.StringValue blockchain_id = 6;                        // bitcoin-private
  google.protobuf.StringValue address = 7;                              // bcrt1qnqx8ltjez3jak8f859y20darrhawa8rq73pank
  google.protobuf.StringValue tag = 8;                                  // null
  repeated .swisschain.sirius.api.common.NullableTagType tag_type = 9;  // NullableTagType.Value.Text
  swisschain.sirius.api.common.PaginationInt64 pagination = 10;         // Pagination object
}

Response

GET /api/accounts/{accountId}/details 200 OK

{
    "pagination":
    {
        "cursor":null,
        "count":5,
        "order":"asc",
        "nextUrl":null
    },
    "items":[
        {
            "id":104000000,
            "accountId":103000000,
            "createdAt":"2020-09-08T13:10:34.719982+00:00",
            "address":"bcrt1qnqx8ltjez3jak8f859y20darrhawa8rq73pank",
            "blockchainId":"bitcoin-private",
            "tag":null,
            "tagType":null},]}
swisschain.sirius.api.accounts.Accounts.SearchDetails

> Response: (application/grpc) - success response

message AccountDetailsSearchResponse {
    oneof result {
      ccountDetailsSearchResponseBody body = 1;
      swisschain.sirius.api.common.ErrorResponseBody error = 2;
  } 
}

message AccountDetailsSearchResponseBody {
   swisschain.sirius.api.common.PaginatedInt64Response pagination = 1;  // Object
   repeated AccountDetailsResponse items = 2;                            // Paginated array of account details
}

message AccountDetailsResponse {
  int64 id = 1;                                                 // 104000000
  int64 account_id = 2;                                         // 103000000
  google.protobuf.Timestamp createdAt = 3;                      // "2020-09-08T13:10:34.719982+00:00"
  string address = 4;                                           // "bcrt1qnqx8ltjez3jak8f859y20darrhawa8rq73pank"
  string blockchain_id = 5;                                     // "bitcoin-private"
  google.protobuf.StringValue tag = 6;                          // null
  swisschain.sirius.api.common.NullableTagType tag_type = 7;    // null
}

Paginated array of the account details:

REST name gRPC name type description
id id number ID of the account details
blockchainId blockchain_id string Blockchain ID
accountId account_id number Id of the related Account
createdAt created_at timestamp Date of the account details creation
address address number Details public address
tag tag optional, string Tag which is related to address (applicable for Stellar)
tagType tag_type optional, TagType Tag type

Gets the account details by the asset id

Request

Rest API: GET /api/accounts/{accountId}/details/by-asset-id/{assetId}

gRPC API: swisschain.sirius.api.accounts.Accounts.GetDetails

Query Parameters

REST name gRPC name type description example
accountId account_id number ID of the account 103000000
assetId asset_id number Id of the asset 100000113
swisschain.sirius.api.accounts.Accounts.GetDetails

> Requets: (application/grpc)

message AccountGetDetailsRequest {
  int64 account_id = 1;                         // 103000000
  int64 asset_id = 2;                           // 100000113
}

Response

GET /api/accounts/103000000/details/by-asset-id/100000113 200 OK

> Response: 200 (application/json) - success response

{
    "id":104000000,
    "accountId":103000000,
    "createdAt":"2020-09-08T13:10:34.719982+00:00",
    "address":"bcrt1qnqx8ltjez3jak8f859y20darrhawa8rq73pank",
    "blockchainId":"bitcoin-private",
    "tag":null,
    "tagType":null
}
swisschain.sirius.api.accounts.Accounts.Search

> Response: (application/grpc) - success response

message AccountGetDetailsResponse {
    oneof result {
      AccountGetDetailsResponseBody body = 1;                     // Object
      swisschain.sirius.api.common.ErrorResponseBody error = 2;   // Object
    } 
}

message AccountGetDetailsResponseBody {
   AccountDetailsResponse account_detail = 1;                   // Object
}

message AccountDetailsResponse {
  int64 id = 1;                                                 // 104000000
  int64 account_id = 2;                                         // 103000000
  google.protobuf.Timestamp createdAt = 3;                      // "2020-09-08T13:10:34.719982+00:00"
  string address = 4;                                           // "bcrt1qnqx8ltjez3jak8f859y20darrhawa8rq73pank"
  string blockchain_id = 5;                                     // "bitcoin-private"
  google.protobuf.StringValue tag = 6;                          // null
  swisschain.sirius.api.common.NullableTagType tag_type = 7;    // null
}
REST name gRPC name type description
id id number ID of the account details
blockchainId blockchain_id string Blockchain ID
accountId account_id number Id of the related Account
createdAt created_at timestamp Date of the account details creation
address address number Details public address
tag tag optional, string Tag which is related to address (applicable for Stellar)
tagType tag_type optional, TagType Tag type

Search for account updates

Request

gRPC API: swisschain.sirius.api.accounts.Accounts.GetUpdates

Parameters

REST name gRPC name type description example
- account_id optional, number Exact account id to search updates for 100000113
- broker_account_id optional, number Exact broker account id to search 103000113
- reference_id optional, string Account reference id user reference
- state optional, AccountState State of the account creating
- pagination.cursor optional, string Cursor to continue the search 11111110
swisschain.sirius.api.accounts.Accounts.GetUpdates

> Requets: (application/grpc)

message AccountUpdateSearchRequest {
  google.protobuf.Int64Value account_id = 1;            // 100000113
  google.protobuf.Int64Value broker_account_id = 2;     // 103000113
  repeated AccountStateModel state = 3;                 // AccountStateModel.Creating
  google.protobuf.StringValue reference_id = 4;         // user reference
  google.protobuf.Int64Value cursor = 5;                // 108000004 (could be empty)
}

Response

swisschain.sirius.api.accounts.Accounts.GetUpdates

> Response: (application/grpc) - success response

message AccountUpdateArrayResponse{
  repeated AccountUpdateResponse items = 1;
}

message AccountUpdateResponse {
  int64 account_update_id = 1;                          // 104000001        
  int64 account_id = 2;                                 // 103000158
  string reference_id = 3;                              // "user reference" 
  int64 broker_account_id = 4;                          // 100000113
  AccountStateModel state = 5;                          // AccountStateModel.Creating
  google.protobuf.Timestamp createdAt = 6;              // "2021-03-26T14:14:46.089822+00:00"
  google.protobuf.Timestamp updatedAt = 7;              // "2021-03-26T14:14:46.089822+00:00"
  google.protobuf.Int64Value user_id = 8;               // 108000004
  google.protobuf.StringValue user_native_id = 9;       // "chainalysis-user-1"
}

Response is the stream of historical account updates and real time updates as well:

REST name gRPC name type description
- account_update_id number ID of the account update
- id number ID of the account
- reference_id optional, string Account reference id
- broker_account_id number Id of the related Broker Account
- status AccountState Status of the account
- created_at timestamp Date of the account creation
- updated_at timestamp Date of the latest account update
- user_id optional, number Id of the related user in the system (Needed for enabling AML on broker Account)
- user_native_id optional, string Native Id of the user in customer's system

Deposits

Deposits reflects incoming transfers of the funds either to an account or directly to the broker account. You can get deposits history, or be notified about new deposits or state changing of the existing deposits. There are different options to be notified about deposits state changing:

Every deposit is associated with a broker account, an asset, optionally an account, it has amount, fees and state. If the account associated with the deposit has reference ID, you can find this value in the deposit too.

In the case if the deposit amount is too small to transfer funds from the account address to the broker account address because amount even doesn't cover fees or not significantly greater than fees, the deposited funds will be keept on the account address until the next deposit with enough amount. We use term "Tiny" for such deposits. If deposit destination is a broker account instead of an account, we name such deposits "Broker deposits".

If user deposited an asset which is not blockchain native (a token), the deposit is classified as "Token" deposit. The lifecycle of a "Token" deposit:

Deposit lifecycle

Searches deposits

Request

Rest API: GET /api/deposits

gRPC API: swisschain.sirius.api.deposits.Deposits.Search

Query Parameters

REST name gRPC name type description example
id id optional, number Exact deposit ID to search 500000113
brokerAccountId broker_account_id optional, number ID of the broker account 100000113
state state optional, Array of DepositState State of the deposit detected
type deposit_type optional, Array of DepositType State of the deposit regular
accountId accountId optional, number ID of the account 200000113
assetId asset_id optional, number ID of the asset 100000
blockchainId blockchain_id optional, string ID of the blockchain ethereum-test
referenceId reference_id optional, string Reference ID of the account ethereum-test
order pagination.order optional, Order Result items sorting order asc
cursor pagination.cursor optional, string Cursor to continue the search 11111110
limit pagination.limit optional, number Maximum number of items to return in the search results 10
swisschain.sirius.api.deposits.Deposits.Search

> Requets: (application/grpc)

message DepositSearchRequest {
  google.protobuf.Int64Value id = 1;
  google.protobuf.Int64Value broker_account_id = 2;
  google.protobuf.Int64Value account_id = 3;
  google.protobuf.StringValue reference_id = 4;
  google.protobuf.Int64Value asset_id = 5;
  google.protobuf.StringValue blockchain_id = 6;
  repeated DepositState state = 7;
  swisschain.sirius.api.common.PaginationInt64 pagination = 8;
  repeated DepositType deposit_type = 9;
}

Response

GET /api/deposits

> Response: 200 (application/json) - success response

{
    "pagination":{
        "cursor":null,
        "count":10,
        "order":"desc",
        "nextUrl":"/api/deposits?Order=Desc&Cursor=105000380&Limit=10"
        },
        "items":[
            {
         "id":105000389,
         "brokerAccountId":100000113,
         "brokerAccountDetails":{
            "id":101000254,
            "address":"0x02d45A855dB2dD98899cdA9a58c16E8f4A1faA96"
         },
         "accountId":null,
         "referenceId":null,
         "accountDetails":null,
         "assetId":100004,
         "blockchainId":"ethereum-ropsten",
         "fees":[
            {
               "assetId":100004,
               "amount":0.000957528
            },
            {
               "assetId":100006,
               "amount":0.0000000176
            },
            {
               "assetId":100007,
               "amount":0.000000000000054405
            }
         ],
         "transactionInfo":{
            "transactionId":"0x29f5b19e76977118d96dba56306c46b6a5406d12da11a1f20add96d002b6d139",
            "transactionBlock":9890232,
            "confirmationsCount":58738,
            "requiredConfirmationsCount":3,
            "date":"2021-03-22T15:40:58Z"
         },
         "state":"completed",
         "sources":[
            {
               "address":"0x1Eab7d412a25a5d00Ec3d04648aa54CeA4aB7e94",
               "amount":0.3803696
            }
         ],
         "amount":0.38,
         "createdAt":"2021-03-22T15:41:12.43838Z",
         "updatedAt":"2021-03-22T15:42:22.412655Z",
         "requiredConfirmationsCount":3,
         "assetSymbol":"ETH",
         "assetAddress":null,
         "blockchainName":"Ethereum test network",
         "brokerAccountName":"AmlCheck-3",
         "depositType":"broker",
         "consolidationTransactionInfo":null,
         "provisioningTransactionInfo":null,
         "amlChecks":{
            "overallResolution":"succeeded",
            "startedAt":"2021-03-22T19:42:15.178434+04:00",
            "completedChecks":[
               {
                  "amlCheckId":601000004,
                  "amlConnectionId":600000012,
                  "resolution":"unknown",
                  "finishedAt":"2021-03-22T15:42:19.2085083+00:00"
               }
            ],
            "requiredChecks":1
         },
         "sequence":3
      }, ...]
}

swisschain.sirius.api.deposits.Deposits.Search

> Response: (application/grpc) - success response

message DepositSearchResponse {
  oneof result {
    DepositSearchResponseBody body = 1;
    swisschain.sirius.api.common.ErrorResponseBody error = 2;
  } 
}

message DepositSearchResponseBody {
  swisschain.sirius.api.common.PaginatedInt64Response pagination = 1;
  repeated DepositResponse items = 2;
}

message DepositResponse {
  int64 id = 1;
  int64 broker_account_id = 2;
  swisschain.sirius.api.common.BrokerAccountDetails broker_account_details = 3;
  google.protobuf.Int64Value account_id = 4;
  google.protobuf.StringValue reference_id = 5;
  swisschain.sirius.api.common.AccountDetails account_details = 6;
  int64 asset_id = 7;
  string blockchain_id = 8;
  repeated swisschain.sirius.api.common.Fee fees = 9;
  swisschain.sirius.api.common.TransactionInfo transaction_info = 10;
  DepositState state = 11;
  repeated DepositSource sources = 12;
  swisschain.sirius.api.common.BigDecimal amount =13;
  google.protobuf.Timestamp created_at = 14;
  google.protobuf.Timestamp updated_at = 15;   
  int64 required_confirmations_count = 16;
  string asset_symbol = 17;
  google.protobuf.StringValue asset_address = 18;
  string blockchain_name = 19;
  string broker_account_name = 20;
  DepositType deposit_type = 21;
  swisschain.sirius.api.aml.AmlChecks aml_checks = 22;
}

Paginated response of the deposits:

REST name gRPC name type description
id id number ID of the deposit
brokerAccountId broker_account_id number Relevant broker account ID
brokerAccountDetails broker_account_details BrokerAccountDetails Broker account details
accountId account_id optional, number Account ID if type is not Broker
referenceId reference_id optional, string Account reference ID if type is not Broker
accountDetails account_details optional, AccountDetails Account details if type is not Broker
assetId asset_id number Asset ID of the deposit transaction
blockchainId blockchain_id string Blockchain ID of the deposit transaction
fees fees Array of Fee Array of spent fees if type is not Broker
transactionInfo transaction_info TransactionInfo Transaction info of incoming transaction
state state DepositState State of the deposit
sources sources Array of DepositSources Sources of the deposit transaction
amount amount decimal Amount of the deposit transaction
createdAt created_at timestamp Date of the deposit creation
updatedAt updated_at timestamp Date of the latest deposit update
requiredConfirmationsCount required_confirmations_count number Required confirmations count for transaction
assetSymbol asset_symbol string Asset symbol (BTC, ETH)
assetAddress asset_address string Asset address (ERC20)
blockchainName blockchain_name string Name of the blockchain
brokerAccountName broker_account_name string Name of the broker account
depositYype deposit_type DepositType Deposit type
amlChecks aml_checks AmlChecks AML checks root object

Searches deposit updates

Request

gRPC API: swisschain.sirius.api.deposits.Deposits.GetUpdates

Parameters

REST name gRPC name type description example
- deposit_id optional, number Exact deposit ID to search 500000113
- deposit_update_id optional, number Exact deposit update ID to search 600000001
- broker_account_id optional, number ID of the broker account 100000113
- state optional, Array of DepositState State of the deposit detected
- deposit_type optional, Array of DepositType State of the deposit regular
- accountId optional, number ID of the account 200000113
- asset_id optional, number ID of the asset 100000
- blockchain_id optional, string ID of the blockchain ethereum-test
- reference_id optional, string Reference ID of the account ethereum-test
- pagination.order optional, Order Result items sorting order asc
- pagination.cursor optional, string Cursor to continue the search 11111110
- pagination.limit optional, number Maximum number of items to return in the search results 10
swisschain.sirius.api.deposits.Deposits.GetUpdates

> Requets: (application/grpc)

message DepositUpdateSearchRequest {
  google.protobuf.Int64Value deposit_id = 1;
  google.protobuf.Int64Value broker_account_id = 2;
  google.protobuf.Int64Value account_id = 3;
  google.protobuf.StringValue reference_id = 4;
  google.protobuf.Int64Value asset_id = 5;
  google.protobuf.StringValue blockchain_id = 6;
  repeated DepositState state = 7;
  google.protobuf.Int64Value deposit_update_id = 8;
  google.protobuf.Int64Value cursor = 9;
  repeated DepositType deposit_type = 10;
}

Response

swisschain.sirius.api.deposits.Deposits.Search

> Response: (application/grpc) - success response

message DepositUpdateArrayResponse{
  repeated DepositUpdateResponse items = 1;
}

message DepositUpdateResponse {
  int64 deposit_id = 1;
  int64 broker_account_id = 2;
  swisschain.sirius.api.common.BrokerAccountDetails broker_account_details = 3;
  google.protobuf.Int64Value account_id = 4;
  google.protobuf.StringValue reference_id = 5;
  swisschain.sirius.api.common.AccountDetails account_details = 6;
  int64 asset_id = 7;
  string blockchain_id = 8;
  repeated swisschain.sirius.api.common.Fee fees = 9;
  swisschain.sirius.api.common.TransactionInfo transaction_info = 10;
  DepositState state = 11;
  repeated DepositSource sources = 12;
  swisschain.sirius.api.common.BigDecimal amount =13;
  google.protobuf.Timestamp created_at = 14;
  google.protobuf.Timestamp updated_at = 15;
  int64 required_confirmations_count = 16;
  string asset_symbol = 17;
  google.protobuf.StringValue asset_address = 18;
  string blockchain_name = 19;
  string broker_account_name = 20;
  int64 deposit_update_id = 21;
  DepositType deposit_type = 22;
  swisschain.sirius.api.aml.AmlChecks aml_checks = 23;
}

Paginated response of the deposits:

REST name gRPC name type description
- deposit_id number ID of the deposit
- deposit_update_id number ID of the deposit update
- broker_account_id number Relevant broker account ID
- broker_account_details BrokerAccountDetails Broker account details
- account_id optional, number Account ID if type is not Broker
- reference_id optional, string Account reference ID if type is not Broker
- account_details optional, AccountDetails Account details if type is not Broker
- asset_id number Asset ID of the deposit transaction
- blockchain_id string Blockchain ID of the deposit transaction
- fees Array of Fee Array of spent fees if type is not Broker
- transaction_info TransactionInfo Transaction info of incoming transaction
- state DepositState State of the deposit
- sources Array of DepositSources Sources of the deposit transaction
- amount decimal Amount of the deposit transaction
- created_at timestamp Date of the deposit creation
- updated_at timestamp Date of the latest deposit update
- required_confirmations_count number Required confirmations count for transaction
- asset_symbol string Asset symbol (BTC, ETH)
- asset_address string Asset address (ERC20)
- blockchain_name string Name of the blockchain
- broker_account_name string Name of the broker account
- deposit_type DepositType Deposit type
- aml_checks AmlChecks AML checks root object

Withdrawals

Withdrawal refers to outgoing transfers of the funds from a broker account. You can get withdrawals history, or be notified about new withdrawals and state changing of the existing withdrawals. There are different options to be notified about withdrawals state changing:

Withdrawal can be initiated by you via API or Universe portal UI. Every withdrawal is associated with a broker account, an asset, optionally an account, your internal ID, it has amount, fees and state. If you use reference ID for the accounts, you can specify either account ID or reference ID, to associate an account to the withdrawal. This link doesn't affect funds flow, it's used just for the reporting and notifying you back with withdrawal updates.

The fees required for the withdrawal transaction are paid atop of the specified amount.

The lifecycle of a withdrawal:

Withdrawal lifecycle

Starts a withdrawal

Request

Rest API: POST /api/withdrawals gRPC API: swisschain.sirius.api.withdrawals.Withdrawals.Execute

POST /api/withdrawals

> Request: (application/json)

x-request-id: 1a5c0b3d15494ec8a390fd3b22d757d6

{
  "document": "{\"version\":\"1.0\",\"brokerAccountId\":100000162,\"accountId\":103000171,\"accountReferenceId\":99,\"withdrawalReferenceId\":76766,\"assetId\":112248,\"amount\":\"0.053\",\"destinationDetails\":{\"address\":\"0x45238387503b485ae1a279d8B420f0e8562bfa35\",\"tag\":null,\"tag_type\":null},\"fee_payer\":\"sender\"}",
  "signature": "CBAirYR2d6vmRV6d1GEfdA3Kv11pOvdebhEyx8pGNKvTaQcbc0IiBUKCESX9eiOlxorkMDuOEMVs4HZ6JnKg6aY8akb72723cBTxvNIHb/P3OyHQWECcIKwmruWXEunWS8ZlFjxy/nWr/XGD0G8N8/xREGhGCcHCjdwrMmMQBSg="
}


swisschain.sirius.api.withdrawals.Withdrawals.Execute

> Requests: (application/grpc)

message WithdrawalExecuteRequest {
    string request_id = 1; // 3a2b59a1-07e5-48b1-ba8b-4b3c750a2aa1
    string document = 2; // "{\"version\":\"1.0\",\"brokerAccountId\":100000162,\"accountId\":103000171,\"accountReferenceId\":99,\"withdrawalReferenceId\":76766,\"assetId\":112248,\"amount\":\"0.053\",\"destinationDetails\":{\"address\":\"0x45238387503b485ae1a279d8B420f0e8562bfa35\",\"tag\":null,\"tag_type\":null},\"fee_payer\":\"sender\"}"
    string signature = 3; // "CBAirYR2d6vmRV6d1GEfdA3Kv11pOvdebhEyx8pGNKvTaQcbc0IiBUKCESX9eiOlxorkMDuOEMVs4HZ6JnKg6aY8akb72723cBTxvNIHb/P3OyHQWECcIKwmruWXEunWS8ZlFjxy/nWr/XGD0G8N8/xREGhGCcHCjdwrMmMQBSg="
}

Parameters

REST name gRPC name type REST placement description
X-Request-ID - string header Unique ID of the request
- request_id string - Unique ID of the request
document document optional, serialized-as-string, WithdrawalDocument body JSON-formatted document describing the withdrawals parameters serialized as string
signature signature optional, string body Base64-encoded RSA signature of the document signed with the Customer's private key
Withdrawal document format:

{
    "version": "string",                // "1.0"
    "brokerAccountId": 1000000,
    "accountId": 1000000,               // Optional
    "accountReferenceId": "string",     // Optional
    "withdrawalReferenceId": "string",  // Optional
    "assetId": 1000000,
    "amount": "decimal",                // 12.345,
    "destinationDetails": {
        "address": "string",            // Blockchain address
        "tag": "string",                // Optional
        "tagType": "string",            // Optional - ("text", "number")
    },
    "feePayer": "sender",
}

Query Parameters

Response

POST /api/withdrawals

> Response: 200 (application/json) - success response

{
 "id":106000003,
 "brokerAccountId":100000005,
 "brokerAccountName":"Hot wallet",
 "brokerAccountDetails":  {
  "id":101000015,
  "address":"0xB335c0a4c4D07164788682Abb9806B0aBd8AB096"
   },
 "accountId":null,
 "accountDetails":null,
 "assetId":112248,
 "assetSymbol":"ETH",
 "assetAddress":null,
 "amount":0.0001,
 "blockchainId":"ethereum-ropsten",
 "blockchainName":"Ethereum Ropsten",
 "fees":[],
 "destinationDetails":{
  "address":"0x45238387503b485ae1a279d8B420f0e8562bfa35",
  "tag":null,
  "tagType":null
  },
 "state":"processing",
 "transactionInfo":null,
 "error":null,
 "operationId":null,
 "requiredConfirmationsCount":-1,
 "transferContext": {
  "accountReferenceId":null,
  "withdrawalReferenceId":null,
  "document":"{\"version\":\"1.0\",\"brokerAccountId\":100000005,\"accountId\":null,\"accountReferenceId\":null,\"withdrawalReferenceId\":null,\"assetId\":112248,\"amount\":0.0001,\"destinationDetails\":{\"address\":\"0x45238387503b485ae1a279d8B420f0e8562bfa35\",\"tagType\":null,\"tag\":null}}",
  "signature":null,
  "requestContext":{
   "userId":"67070a1f-033a-4ed9-ad1e-1214291687d0",
   "apiKeyId":null,
   "ip":"192.168.16.36",
   "timestamp":"2021-03-31T11:46:46.059629Z"
   }
  },
  "validatorContext":null,
  "createdAt":"2021-03-31T11:46:46.614955Z",
  "updatedAt":"2021-03-31T11:46:46.614955Z",
  "feePayer": "sender"
}
swisschain.sirius.api.withdrawals.Withdrawals.Execute

> Response: (application/grpc) - success response

message WithdrawalExecuteResponse {
    oneof result {
        WithdrawalExecuteResponseBody body = 1;
        WithdrawalExecuteErrorResponseBody error = 2;
    }
}

message WithdrawalExecuteResponseBody {
    WithdrawalResponse withdrawal = 1;
}

message WithdrawalResponse {
    int64 id = 1;
    int64 broker_account_id = 2;
    string broker_account_name = 3;
    swisschain.sirius.api.common.BrokerAccountDetails broker_account_details = 4;
    google.protobuf.Int64Value account_id = 5;
    swisschain.sirius.api.common.AccountDetails account_details = 6;
    google.protobuf.StringValue account_reference_id = 7;
    int64 asset_id = 8;
    string asset_symbol = 9;
    google.protobuf.StringValue asset_address = 10;
    swisschain.sirius.api.common.BigDecimal amount = 11;
    string blockchain_id = 12;
    string blockchain_name = 13;
    repeated swisschain.sirius.api.common.Fee fee = 14;
    DestinationDetails destination_details = 15;
    WithdrawalState state = 16;
    swisschain.sirius.api.common.TransactionInfo transaction_info = 17;
    WithdrawalError error = 18;
    google.protobuf.Int64Value operation_id = 19;
    int64 required_confirmations_count = 20;
    TransferContext transfer_context = 21;
    ValidatorContext validator_context = 22;
    google.protobuf.Timestamp created_at = 23;
    google.protobuf.Timestamp updated_at = 24;
}

Parameters

REST name gRPC name type description
id id number ID of the withdrawal
brokerAccountId broker_account_id number ID of the broker account
brokerAccountName broker_account_name string Name of the broker account
brokerAccountDetails broker_account_details string Details of broker account wallet
accountId account_id number ID of the account
accountDetails account_details string Details of account wallet
- account_reference_id string Reference of account
assetId asset_id number ID of the asset
assetSymbol asset_symbol string Symbol of the asset
assetAddress asset_address string Address of the asset (for ERC20/223)
amount amount decimal Withdrawal amount
blockchainId blockchain_id number Id of blockhain used for withdrawal
blockchainName blockchain_name string Name of blockhain used for withdrawal
fees fee decimal Fee details
destinationDetails destination_details string Details of destination wallet
state state string State of withdrawal
transactionInfo transaction_info string Unique ID of the request
error error string Error details if withdrawal failed
operationId operation_id number Id of operation
requiredConfirmationsCount required_confirmations_count number -
transferContext transfer_context string Details of initial transfer with document
validatorContext validator_context string Details of validator response
createdAt created_at timestamp Datetime of withdrawal creation
updatedAt updated_at timestamp Datetime of latest withdrawal update
feePayer fee_payer string either 'sender' or 'recipient'

''

Searches withdrawals

Request

Rest API: GET /api/withdrawals gRPC API: swisschain.sirius.api.withdrawals.Withdrawals.Search

swisschain.sirius.api.withdrawals.Withdrawals.Search

> Requets: (application/grpc)

{
  "id": {
    "value": 106000107
  },
  "broker_account_id": {
    "value": 100000062
  },
  "account_id": {
    "value": 103001270
  },
  "asset_id": {
    "value": 300000004
  },
  "blockchain_id": {
    "value": "ethereum-ropsten"
  },
  "state": [ ],
  "transaction_id": null,
  "error_code": [ ],
  "operation_id": null,
  "destination_address": {
    "value": "0xBB7cfa448FedDe5c5593ca4487d76A580aFfef71"
  },
  "destination_tag": null,
  "destination_tag_type": null,
  "pagination": {
    "order": 0,
    "cursor": {
      "value": 0
    },
    "limit": 10
  },
  "account_reference_id": {
    "value": "newerc"
  },
  "user_id": {
    "value": 108000015
  },
  "user_native_id": {
    "value": "us1"
  },
  "fee_payer":"sender"
}


message WithdrawalSearchRequest {
    google.protobuf.Int64Value id = 1;
    google.protobuf.Int64Value broker_account_id = 2;
    google.protobuf.Int64Value account_id = 3;
    google.protobuf.Int64Value asset_id = 4;
    google.protobuf.StringValue blockchain_id = 5;
    repeated WithdrawalState state = 6;
    google.protobuf.StringValue transaction_id = 7;
    repeated WithdrawalErrorCode error_code = 8;
    google.protobuf.Int64Value operation_id = 9;
    google.protobuf.StringValue destination_address = 10;
    google.protobuf.StringValue destination_tag = 11;
    swisschain.sirius.api.common.NullableTagType destination_tag_type = 12;
    swisschain.sirius.api.common.PaginationInt64 pagination = 13;
    google.protobuf.StringValue account_reference_id = 14;
    google.protobuf.Int64Value user_id = 15;
    google.protobuf.StringValue user_native_id = 16;
}

Query Parameters

REST name gRPC name type description example
id id optional, number Exact deposit ID to search 106000107
brokerAccountId broker_account_id optional, number ID of the broker account 100000062
accountId account_id optional, number ID of the account 103001270
accountReferenceId account_reference_id optional, string Reference ID of the account newerc
userId user_id optional, string Reference ID of the user with AML relations 108000015
userNativeId user_native_id optional, string Reference ID or Name of the account inside AML system us1
assetId asset_id optional, number ID of the asset 300000004
blockchainId blockchain_id optional, string ID of the blockchain ethereum-ropsten
state state optional, Array of WithdrawalState State of the withdrawal sent
transactionId transaction_id optional, number ID of the transaction 300000123
errorCode error_code optional, Array of WithdrawalError Reason of the failed withdrawal invalidDestinationAddress
operationId operation_id optional, number ID of the operation 400000543
destinationAddress destination_address optional, string Address of destination wallet 0xBB7cfa448FedDe5c5593ca4487d76A580aFfef71
destinationTag destination_Tag optional, string or number Address extension of destination wallet MyStellarMemo / 200004
destinationTagType destination_tag_type optional, string or number Select type of destination tag Text / Number
order pagination.order optional, Order Result items sorting order asc
cursor pagination.cursor optional, string Cursor to continue the search 11111110
limit pagination.limit optional, number Maximum number of items to return in the search results 10

Response

GET /api/withdrawals 200 OK swisschain.sirius.api.withdrawals.Withdrawals.Search Success

{
  "pagination":
  {
    "cursor": null,
    "count": 1,
    "order": "desc",
    "nextUrl": null
  },
  "items":
  [
    {
      "id": 106000107,
      "brokerAccountId": 100000062,
      "brokerAccountName": "broker3",
      "brokerAccountDetails":
      {
        "id": 101000172,
        "address": "0x0DB6947809533142C0D8993FD466A5fa890DB68a"
      },
      "accountId": 103001270,
      "accountReferenceId": "newerc",
      "userId": 108000015,
      "userNativeId": "us1",
      "assetId": 300000004,
      "assetSymbol": "ETH",
      "assetAddress": null,
      "amount": 0.1,
      "blockchainId": "ethereum-ropsten",
      "blockchainName": "Ethereum Ropsten",
      "fees":
      [],
      "destinationDetails":
      {
        "address": "0xBB7cfa448FedDe5c5593ca4487d76A580aFfef71",
        "tag": null,
        "tagType": null
      },
      "state": "completed",
      "transactionInfo":
      {
        "transactionId": "0x64e3283c885ad7a75e7c79de4eddce59db1c8c753da291181c093f45d70e5374",
        "transactionBlock": 11360334,
        "confirmationsCount": 43983,
        "requiredConfirmationsCount": 0,
        "date": "0001-01-01T00:00:00Z"
      },
      "error": null,
      "operationId": 200000270,
      "requiredConfirmationsCount": 0,
      "transferContext":
      {
        "accountReferenceId": "newerc",
        "withdrawalReferenceId": null,
        "document": "{\"version\":\"1.0\",\"brokerAccountId\":100000062,\"accountId\":null,\"accountReferenceId\":\"newerc\",\"withdrawalReferenceId\":null,\"assetId\":300000004,\"amount\":0.1,\"destinationDetails\":
    {\"address\":\"0xBB7cfa448FedDe5c5593ca4487d76A580aFfef71\",\"tagType\":null,\"tag\":null}}",
    "signature": null,
    "requestContext":
    {
      "userId": "0dde3a01-f675-439a-9439-0d1198ddaf8b",
      "apiKeyId": null,
      "ip": "10.244.4.0",
      "timestamp": "2021-11-04T10:46:39.7480342Z"
    }
    },
    "validatorContext":
    {
      "document": "{\"validationRequestId\":419000075,\"tenantId\":\"b25e5938-83d5-4d37-b3d1-858f65bfb52b\",\"validatorResolutions\":
    [{\"validatorId\":\"bEJgk7EgkPhKeoN4r+xI7sLzhLDYRf7IQ5XW86KdN7E=\",\"document\":\"{\\\"resolution\\\":\\\"Approved\\\",\\\"resolutionMessage\\\":\\\"\\\",\\\"transfer\\\":{\\\"blockchain\\\":{\\\"id\\\":\\\"ethereum-ropsten\\\",\\\"protocolId\\\":\\\"ethereum\\\",\\\"networkType\\\":\\\"Test\\\"},\\\"context\\\":{\\\"component\\\":\\\"Brokerage\\\",\\\"document\\\":\\\"{\\\\\\\"version\\\\\\\":\\\\\\\"1.0\\\\\\\",\\\\\\\"brokerAccountId\\\\\\\":100000062,\\\\\\\"accountId\\\\\\\":null,\\\\\\\"accountReferenceId\\\\\\\":\\\\\\\"newerc\\\\\\\",\\\\\\\"withdrawalReferenceId\\\\\\\":null,\\\\\\\"assetId\\\\\\\":300000004,\\\\\\\"amount\\\\\\\":0.1,\\\\\\\"destinationDetails\\\\\\\":{\\\\\\\"address\\\\\\\":\\\\\\\"0xBB7cfa448FedDe5c5593ca4487d76A580aFfef71\\\\\\\",\\\\\\\"tagType\\\\\\\":null,\\\\\\\"tag\\\\\\\":null}}\\\",\\\"documentVersion\\\":null,\\\"operationType\\\":\\\"Withdrawal\\\",\\\"signature\\\":null,\\\"withdrawalReferenceId\\\":null,\\\"requestContext\\\":{\\\"apiKeyId\\\":null,\\\"ip\\\":\\\"10.244.4.0\\\",\\\"timestamp\\\":\\\"2021-11-04T10:46:39.748034200Z\\\",\\\"userId\\\":\\\"0dde3a01-f675-439a-9439-0d1198ddaf8b\\\"}},\\\"destination\\\":{\\\"address\\\":\\\"0xBB7cfa448FedDe5c5593ca4487d76A580aFfef71\\\",\\\"tag\\\":null,\\\"tagType\\\":null},\\\"fee\\\":{\\\"amount\\\":0.000063,\\\"asset\\\":{\\\"address\\\":null,\\\"id\\\":300000004,\\\"symbol\\\":\\\"ETH\\\"}},\\\"id\\\":200000270,\\\"source\\\":{\\\"address\\\":\\\"0x0DB6947809533142C0D8993FD466A5fa890DB68a\\\",\\\"brokerAccount\\\":{\\\"id\\\":100000062,\\\"name\\\":\\\"broker3\\\"}},\\\"value\\\":{\\\"amount\\\":0.1,\\\"asset\\\":{\\\"address\\\":null,\\\"id\\\":300000004,\\\"symbol\\\":\\\"ETH\\\"}}}}\",\"signature\":\"fAF7MzJ0EhsLEqUKtUkZqd19nETlBHMmIg6oz1Ur+JYJYEV37Wjw30rqpciVe7YInKifdzxcvYYlGx+nvgyGjlJATJOsdWSu3nUa/YYbx9eUGX2m18h7FHoQI4CCXBwJkwTJ/aKkbdwkaOzEy6/4eel34xpLeji957Q7DF1j/ig=\",\"resolution\":\"Approved\",\"resolutionMessage\":\"\",\"deviceInfo\":\"{\\\"deviceUID\\\":\\\"8CCC5E5B-38B2-4ACB-B42C-A6713920654F\\\",\\\"platform\\\":\\\"iOS\\\"}\",\"ip\":\"ipv4:10.244.6.0:1728\",\"timestamp\":\"2021-11-04T10:46:55.171321Z\"}],\"requestedValidators\":[\"bEJgk7EgkPhKeoN4r+xI7sLzhLDYRf7IQ5XW86KdN7E=\"],\"status\":\"Approved\",\"rejectReasonMessage\":null,\"timestamp\":\"2021-11-04T10:46:55.263737Z\",\"transfer\":{\"id\":200000270,\"blockchain\":{\"id\":\"ethereum-ropsten\",\"protocolId\":\"ethereum\",\"networkType\":\"Test\"},\"source\":{\"address\":\"0x0DB6947809533142C0D8993FD466A5fa890DB68a\",\"brokerAccount\":{\"id\":100000062,\"name\":\"broker3\"},\"account\":null},\"destination\":{\"address\":\"0xBB7cfa448FedDe5c5593ca4487d76A580aFfef71\",\"tag\":null,\"tagType\":null,\"brokerAccount\":null,\"account\":null},\"value\":{\"asset\":{\"id\":300000004,\"symbol\":\"ETH\",\"address\":null},\"amount\":0.1},\"fee\":{\"asset\":{\"id\":300000004,\"symbol\":\"ETH\",\"address\":null},\"amount\":0.0000630},\"context\":{\"document\":\"{\\\"version\\\":\\\"1.0\\\",\\\"brokerAccountId\\\":100000062,\\\"accountId\\\":null,\\\"accountReferenceId\\\":\\\"newerc\\\",\\\"withdrawalReferenceId\\\":null,\\\"assetId\\\":300000004,\\\"amount\\\":0.1,\\\"destinationDetails\\\":{\\\"address\\\":\\\"0xBB7cfa448FedDe5c5593ca4487d76A580aFfef71\\\",\\\"tagType\\\":null,\\\"tag\\\":null}}\",\"documentVersion\":null,\"signature\":null,\"withdrawalReferenceId\":null,\"component\":\"Brokerage\",\"operationType\":\"Withdrawal\",\"requestContext\":{\"userId\":\"0dde3a01-f675-439a-9439-0d1198ddaf8b\",\"apiKeyId\":null,\"ip\":\"10.244.4.0\",\"timestamp\":\"2021-11-04T10:46:39.748034200Z\"}}}}",
      "signature": "VKwnK35dJaq3ZayUlMtpiZo2T7eCxmwTYHgJbfPjWcwnCzdLLVHU6y5WZaBYgQcVCapZRKnZQUA+5ppjOT2YYZEOUz5vsAWLrIB4U6bJ9/aJ937FnG8rXChWCRzTB/qDxRzv2X/hJFE5RobF9k8M2n6uYi3aHpshX9YUh5qo5Rk="
      },
      "amlChecks":
      {
        "overallResolution": "succeeded",
        "startedAt": "2021-11-04T10:46:40.143002Z",
        "completedChecks":
        [
          {
            "amlCheckId": 602000027,
            "amlConnectionId": 600000010,
            "resolution": "normal",
            "finishedAt": "2021-11-04T10:46:40.2917194Z",
            "description": "Allowed by the whitelist item 603000017 (anyw)"
          }
        ],
        "requiredChecks": 1
      },
      "createdAt": "2021-11-04T10:46:40.00195Z",
      "updatedAt": "2021-11-04T10:48:19.100099Z",
      "sequence": 6
      }
    ]
  }
message WithdrawalResponse {
    int64 id = 1;
    int64 broker_account_id = 2;
    string broker_account_name = 3;
    swisschain.sirius.api.common.BrokerAccountDetails broker_account_details = 4;
    google.protobuf.Int64Value account_id = 5;
    google.protobuf.StringValue account_reference_id = 7;
    int64 asset_id = 8;
    string asset_symbol = 9;
    google.protobuf.StringValue asset_address = 10;
    swisschain.sirius.api.common.BigDecimal amount = 11;
    string blockchain_id = 12;
    string blockchain_name = 13;
    repeated swisschain.sirius.api.common.Fee fee = 14;
    DestinationDetails destination_details = 15;
    WithdrawalState state = 16;
    swisschain.sirius.api.common.TransactionInfo transaction_info = 17;
    WithdrawalError error = 18;
    google.protobuf.Int64Value operation_id = 19;
    int64 required_confirmations_count = 20;
    TransferContext transfer_context = 21;
    ValidatorContext validator_context = 22;
    google.protobuf.Timestamp created_at = 23;
    google.protobuf.Timestamp updated_at = 24;
    google.protobuf.Int64Value user_id = 25;
    google.protobuf.StringValue user_native_id = 26;
    swisschain.sirius.api.aml.AmlChecks aml_checks = 27;
}

message TransferContext {
    google.protobuf.StringValue account_reference_id = 1;
    google.protobuf.StringValue withdrawal_reference_id = 2;
    google.protobuf.StringValue document = 3;
    google.protobuf.StringValue signature = 4;
    RequestContext request_context = 5;
}

message RequestContext {
    google.protobuf.StringValue user_id = 1;
    google.protobuf.StringValue api_key_id = 2;
    google.protobuf.StringValue ip = 3;
    google.protobuf.Timestamp timestamp = 4;
}

message ValidatorContext {
    google.protobuf.StringValue document = 1;
    google.protobuf.StringValue signature = 2;
}

Parameters

Paginated response of the withdrawals:

REST name gRPC name type description
id id number ID of the withdrawal
brokerAccountId broker_account_id number ID of the broker account
brokerAccountName broker_account_name string Name of the broker account
brokerAccountDetails broker_account_details string Details of broker account wallet
accountId account_id number ID of the account
accountDetails account_details string Details of account wallet
accountReferenceId account_reference_id string Reference of account
assetId asset_id number ID of the asset
assetSymbol asset_symbol string Symbol of the asset
assetAddress asset_address string Address of the asset (for tokens like ERC20/223)
amount amount decimal Withdrawal amount
blockchainId blockchain_id number Id of blockhain used for withdrawal
blockchainName blockchain_name string Name of blockhain used for withdrawal
fees fee decimal Fee details
destinationDetails destination_details string Details of destination wallet
state state string State of withdrawal
transactionId transaction_id string Unique ID of the request
error error string Error details if withdrawal failed
operationId operation_id number Id of operation
requiredConfirmationsCount required_confirmations_count number -
transferContext transfer_context string Details of initial transfer with document, signature and request context
validatorContext validator_context string Details of validator response
userId user_id optional, string Reference ID of the user with AML relations
userNativeId user_native_id optional, string Reference ID or Name of the account inside AML system
amlChecks aml_checks string Details of aml providers response
createdAt created_at timestamp Datetime of withdrawal creation
updatedAt updated_at timestamp Datetime of latest withdrawal update

Searches withdrawal updates

Request

Rest API: GET /api/withdrawal-updates gRPC API: swisschain.sirius.api.withdrawals.Withdrawals.GetUpdates

message WithdrawalUpdateSearchRequest {
google.protobuf.Int64Value withdrawal_id = 1;
google.protobuf.Int64Value broker_account_id = 2;
google.protobuf.Int64Value account_id = 3;
google.protobuf.Int64Value asset_id = 4;
google.protobuf.StringValue blockchain_id = 5;
repeated WithdrawalState state = 6;
google.protobuf.StringValue transaction_id = 7;
repeated WithdrawalErrorCode error_code = 8;
google.protobuf.Int64Value operation_id = 9;
google.protobuf.StringValue destination_address = 10;
google.protobuf.StringValue destination_tag = 11;
swisschain.sirius.api.common.NullableTagType destination_tag_type = 12;
google.protobuf.Int64Value withdrawal_update_id = 13;
google.protobuf.Int64Value cursor = 14;
google.protobuf.StringValue account_reference_id = 15;
google.protobuf.Int64Value user_id = 16;
google.protobuf.StringValue user_native_id = 17;
}

example:
{
  "withdrawal_id": null,
  "broker_account_id": {
    "value": 100000062
  },
  "account_id": null,
  "asset_id": {
    "value": 300000004
  },
  "blockchain_id": {
    "value": "ethereum-ropsten"
  },
  "state": [

  ],
  "transaction_id": null,
  "error_code": [

  ],
  "operation_id": null,
  "destination_address": null,
  "destination_tag": null,
  "destination_tag_type": null,
  "withdrawal_update_id": null,
  "cursor": {
    "value": 0
  },
  "account_reference_id": null,
  "user_id": null,
  "user_native_id": null
}

Query Parameters

gRPC name type description example
id withdrawal_id optional, number Exact deposit ID to search
brokerAccountId broker_account_id optional, number ID of the broker account
accountId account_id optional, number ID of the account
accountReferenceId account_reference_id optional, string Reference ID of the account
userId user_id optional, string Reference ID of the user with AML relations
userNativeId user_native_id optional, string Reference ID or Name of the account inside AML system
assetId asset_id optional, number ID of the asset
blockchainId blockchain_id optional, string ID of the blockchain
state state optional, Array of WithdrawalState State of the withdrawal
transactionId transaction_id optional, number ID of the transaction
errorCode error_code optional, Array of WithdrawalError Reason of the failed withdrawal
operationId operation_id optional, number ID of the operation
destinationAddress destination_address optional, string Address of destination wallet
destinationTag destination_Tag optional, string or number Address extension of destination wallet
destinationTagType destination_tag_type optional, string or number Select type of destination tag
withdrawalUpdateId withdrawal_update_id optional, number Exact deposit update ID to search
order - optional, Order Result items sorting order
cursor cursor optional, string Cursor to continue the search
limit - optional, number Maximum number of items to return in the search results

Response

{
  "items": [
    {
      "withdrawal_update_id": "501000593",
      "withdrawal": {
        "fee": [],
        "id": "106000107",
        "broker_account_id": "100000062",
        "broker_account_name": "broker3",
        "broker_account_details": {
          "id": "101000172",
          "address": "0x0DB6947809533142C0D8993FD466A5fa890DB68a"
        },
        "account_id": {
          "value": "103001270"
        },
        "account_reference_id": {
          "value": "newerc"
        },
        "asset_id": "300000004",
        "asset_symbol": "ETH",
        "asset_address": null,
        "amount": {
          "value": "0.1"
        },
        "blockchain_id": "ethereum-ropsten",
        "blockchain_name": "Ethereum Ropsten",
        "destination_details": {
          "address": "0xBB7cfa448FedDe5c5593ca4487d76A580aFfef71",
          "tag": null,
          "tag_type": {
            "null": "NULL_VALUE",
            "kind": "null"
          }
        },
        "state": "PROCESSING",
        "transaction_info": null,
        "error": null,
        "operation_id": null,
        "required_confirmations_count": "-1",
        "transfer_context": {
          "account_reference_id": {
            "value": "newerc"
          },
          "withdrawal_reference_id": null,
          "document": {
            "value": "{\"version\":\"1.0\",\"brokerAccountId\":100000062,\"accountId\":null,\"accountReferenceId\":\"newerc\",\"withdrawalReferenceId\":null,\"assetId\":300000004,\"amount\":0.1,\"destinationDetails\":{\"address\":\"0xBB7cfa448FedDe5c5593ca4487d76A580aFfef71\",\"tagType\":null,\"tag\":null}}"
          },
          "signature": null,
          "request_context": {
            "user_id": {
              "value": "0dde3a01-f675-439a-9439-0d1198ddaf8b"
            },
            "api_key_id": null,
            "ip": {
              "value": "192.168.4.0"
            },
            "timestamp": {
              "seconds": "1636022799",
              "nanos": 748034200
            }
          }
        },
        "validator_context": null,
        "created_at": {
          "seconds": "1636022800",
          "nanos": 1950000
        },
        "updated_at": {
          "seconds": "1636022800",
          "nanos": 1950000
        },
        "user_id": {
          "value": "108000015"
        },
        "user_native_id": {
          "value": "us1"
        },
        "aml_checks": null
      }
    }
  ]
}
message WithdrawalUpdateArrayResponse {
repeated WithdrawalUpdateResponse items = 1;
}

message WithdrawalUpdateResponse {
int64 withdrawal_update_id = 1;
WithdrawalResponse withdrawal = 2;
}

Parameters

GET /api/withdrawal-updates 200 OK Stream swisschain.sirius.api.withdrawals.Withdrawals.GetUpdates

Paginated response of the withdrawals update:

REST name gRPC name type description
withdrawalUpdateId withdrawal_update_id optional, number Exact deposit update ID to search
id id number ID of the withdrawal
brokerAccountId broker_account_id number ID of the broker account
brokerAccountName broker_account_name string Name of the broker account
brokerAccountDetails broker_account_details string Details of broker account wallet
accountId account_id number ID of the account
accountDetails account_details string Details of account wallet
accountReferenceId account_reference_id string Reference of account
assetId asset_id number ID of the asset
assetSymbol asset_symbol string Symbol of the asset
assetAddress asset_address string Address of the asset (for tokens like ERC20/223)
amount amount decimal Withdrawal amount
blockchainId blockchain_id number Id of blockhain used for withdrawal
blockchainName blockchain_name string Name of blockhain used for withdrawal
fees fee decimal Fee details
destinationDetails destination_details string Details of destination wallet
state state string State of withdrawal
transactionId transaction_id string Unique ID of the request
error error string Error details if withdrawal failed
operationId operation_id number Id of operation
requiredConfirmationsCount required_confirmations_count number -
transferContext transfer_context string Details of initial transfer with document, signature and request context
validatorContext validator_context string Details of validator response
userId user_id optional, string Reference ID of the user with AML relations
userNativeId user_native_id optional, string Reference ID or Name of the account inside AML system
amlChecks aml_checks string Details of aml providers response
createdAt created_at timestamp Datetime of withdrawal creation
updatedAt updated_at timestamp Datetime of latest withdrawal update

SmartContracts

Deploy a smart contract

Request

Rest API: POST /api/smart-contracts/deploy gRPC API: swisschain.sirius.api.smart_contracts.SmartContracts.Deploy

POST /api/smart-contracts/deploy

> Request: (application/json, text/plain, */*)

x-request-id: 1a5c0b3d15494ec8a390fd3b22d757d6
x-tfa-code: 000000  


code: (binary)
document: {"name":"mew","referenceId":"qwe","brokerAccountId":100000074,"blockchainId":"ethereum-goerli","arguments":[],"payment":{"assetId":300000010}}
signature: {"JiOtcENJqblnWFcTZ4DiXwUZudlKBUtYnSkUjmfAH/8a1jeMPwFBu8MGjffITh3PRl/VLRTj8kjKWFT8EUR/8Qb3E8dTeuBlCIDU2RlHRRfb6iuTvjlPmUYQ/+Es6oZlH+Tapvjfa57N19poNZ7zimqadsASe3FGt0ME9J5vufE="}


swisschain.sirius.api.smart_contracts.SmartContracts.Deploy

> Requets: (application/grpc)

message SmartContractDeployRequest {
  string request_id = 1; // 1a5c0b3d15494ec8a390fd3b22d757d6
  string document = 2; // {"name":"grpc","brokerAccountId":100000071,"blockchainId":"ethereum-ropsten","arguments":[],"payment":{"assetId":300000004}}
  string signature = 3; // mRMfKO7x3TZYkW4uLOrDfhBOAqAY5hIdAyLLHT/BxzrO8Ophwx/qVHlyQevgj4QVS4RnVMQHJaRDAbyIueduScRSoTXCd6XhZ6m8vA3enWogUuW41CX3+2C1GOF9KvJSBznRb6w5AaUbTaiBcixILz7tcE7hqEW2sZt2LSDGcKs=
  bytes code = 4; // binary(BaseSecurityToken.json)
}

Parameters

REST name gRPC name type REST placement description
x-request-id - string header Unique ID of the request
x-2fa-code - string header 2fa code for corresponding Universe user
- request_id string - Unique ID of the request
document document optional, serialized-as-string, SmartContractDocument body JSON-formatted document describing the deployment parameters serialized as string
signature signature optional, string body Base64-encoded RSA signature of the document signed with the Customer's private key

Query Parameters

Response

POST /api/smart-contracts/deploy

> Response: 200 (application/json) - success response

{
"id": 109000044,
"name": "mew",
"blockchainId": "ethereum-goerli",
"blockchainName": "Ethereum Goerli",
"brokerAccountId": 100000074,
"brokerAccountName": "SCV2New",
"creatorAddress": "0x94afa005a395e470EB56a26E9081dC650EF84732",
"payment":
{
"assetId": 300000010,
"amount": 0.0
},
"arguments":
[],
"state": "processing",
"deploymentContext":
{
"document": "{\"name\":\"mew\",\"referenceId\":\"qwe\",\"brokerAccountId\":100000074,\"blockchainId\":\"ethereum-goerli\",\"arguments\":
[],\"payment\":{\"assetId\":300000010}}",
"codeHash": "0x88604ca3b6d365a9bd9527be0065b6db",
"referenceId": "qwe",
"requestContext":
{
"userId": "0dde3a01-f675-439a-9439-0d1198ddaf8b",
"ip": "192.168.4.0",
"timestamp": "2021-12-09T18:02:42.8053937Z"
}
},
"createdAt": "2021-12-09T18:02:43.0570272Z",
"updatedAt": "2021-12-09T18:02:43.0570272Z"
}
`swisschain.sirius.api.smart_contracts.SmartContracts.Deploy`

message SmartContractDeployResponse {
  oneof result {
    SmartContractDeployResponseBody body = 1;
    swisschain.sirius.api.common.ErrorResponseBody error = 2;
  }
}

message SmartContractDeployResponseBody {
  SmartContractModel item = 1;
}


message SmartContractModel {
  enum SmartContractState
  {
    PROCESSING = 0;
    VALIDATING = 1;
    SIGNING = 2;
    SENT = 3;
    ON_CHAIN = 4;
    COMPLETED = 5;
    FAILED = 6;
    REJECTED = 7;
  }

  int64 id = 1;
  string name = 2;
  google.protobuf.StringValue address = 3;
  string blockchain_id = 4;
  string blockchain_name = 5;
  google.protobuf.Int64Value broker_account_id = 6;
  google.protobuf.StringValue broker_account_name = 7;
  string creator_address = 8;
  PaymentModel payment = 9;
  repeated smart_connect.data_model.Argument arguments = 10;
  SmartContractState state = 11;
  common.TransactionInfo transaction_info = 12;
  SmartContractDeploymentContext deployment_context = 13;
  ValidatorContext validator_context = 14;
  int64 sequence = 15;
  SmartContractError error = 16;
  google.protobuf.Timestamp created_at = 17;
  google.protobuf.Timestamp updated_at = 18;  
}

Parameters

REST name gRPC name type description
id id number ID of the deployment
name name string Name of the smart contract
address address string address of the smart contract
blockchainId blockchain_id number Id of blockchain used for deployment
blockchainName blockchain_name string Name of blockchain used for deployment
brokerAccountId broker_account_id number ID of the broker account
brokerAccountName broker_account_name string Name of the broker account
creator_address creator_address string address of the contract creator
payment payment PaymentModel details for payments executed during deployment
arguments arguments repeated smart_connect.data_model.Argument arguments used for deployment
state state string State of deployment
transactionInfo transaction_info string tx details like hash and confirmations count
deploymentContext deployment_context string Details of initial deploy with document
validatorContext validator_context string Details of validator response
sequence sequence int update sequence
error error string Error details if smart contract failed
createdAt created_at timestamp Datetime of deploy creation
updatedAt updated_at timestamp Datetime of last deploy update

Parse smart contract metamodel

Request

Rest API: Post /api/smart-contracts/parse gRPC API: swisschain.sirius.api.smart_contracts.SmartContracts.Parse

POST /api/smart-contracts/parse

> Request: (application/json, text/plain, */*)


code: (binary)
blockchainId: ethereum

swisschain.sirius.api.smart_contracts.SmartContracts.Parse


message SmartContractParseRequest{
  string blockchain_id = 1; // ethereum
  bytes code = 2; // BaseSecurityToken.json
}

Parameters

REST name gRPC name type description example
blockchainId blockchain_id required, string ID of the blockchain ethereum
code code required, binary compiled smart contract

Response

POST /api/smart-contracts/parse 200 OK

{
  "constructor":
  {
    "isPayable": false,
    "address": "1e6c5609",
    "parameters":
    []
  },
  "readFunctions":
  [
    {
      "name": "decimals",
      "return":
      {
        "returnType":
        {
          "prototype": "void",
          "constraints":
          []
        }
      },
      "address": "313ce567",
      "parameters":
      [
        {
          "name": "out_1",
          "parameterType":
          {
            "prototype": "int",
            "nativeType": "uint8",
            "constraints":
            [
              {
                "type": "required",
                "errorMessage": "Value is required"
              },
              {
                "type": "maxInt",
                "maxInt": 255,
                "errorMessage": "Max value is 255"
              },
              {
                "type": "minInt",
                "minInt": 0,
                "errorMessage": "Min value is 0"
              }
            ]
          },
          "direction": "out"
        }
      ]
    }, ... 1942 more rows
swisschain.sirius.api.smart_contracts.SmartContracts.Parse

message SmartContractParseResponse {
  oneof result {
    SmartContractParseResponseBody body = 1;
    swisschain.sirius.api.common.ErrorResponseBody error = 2;
  }
}

message SmartContractParseResponseBody {
  smart_connect.metamodel.SmartContractInfo metamodel = 1;
}

message SmartContractInfo {
    ConstructorInfo ctor = 1;
    repeated ReadFunctionInfo read_functions = 2;
    repeated WriteFunctionInfo write_functions = 3;
    repeated EventInfo events = 4;
    bytes code = 5; 
}

// Functions

message ConstructorInfo {
    string address = 1;
    bool is_payable = 2;
    repeated ParameterInfo parameters = 3;
}

message ReadFunctionInfo {
    string name = 1;
    string address = 2;
    repeated ParameterInfo parameters = 3;
    ReturnInfo return = 4;
}

message WriteFunctionInfo {
    string name = 1;
    string address = 2;
    bool is_payable = 3;
    repeated ParameterInfo parameters = 4;
    ReturnInfo return = 5;
}

message ParameterInfo {
    string name = 1;
    TypeInfo type = 2;
    ParameterDirection direction = 3;
}

enum ParameterDirection {
    IN = 0;
    OUT = 1;
}

message ReturnInfo {
    string name = 1;
    TypeInfo type = 2;
}

// Events

message EventInfo {
    string name = 1;
    string address = 2;
    TypeInfo type = 3;
}

// Types

message TypeInfo {
  string native_type = 1;
  PrototypeInfo prototype = 2;
  repeated Constraint constraints = 3;
}

message PrototypeInfo {
  oneof kind {
    EnumTypeInfo enum = 1;
    AddressTypeInfo address = 2;
    BoolTypeInfo bool = 3;
    BytesTypeInfo bytes = 4;
    DecimalTypeInfo decimal = 5;
    IntTypeInfo int = 6;
    StringTypeInfo string = 7;
    TimestampTypeInfo timestamp = 8;
    VoidTypeInfo void = 9;
    ArrayTypeInfo array = 10;
    CompositeTypeInfo composite = 11;
    EitherTypeInfo either = 12;
    MapTypeInfo map = 13;
  }
}

message EnumTypeInfo {
    repeated EnumFieldInfo fields = 1;
}

message EnumFieldInfo {
    string name = 1;
    int32 value = 2;
}

message AddressTypeInfo {
}

message BoolTypeInfo {
}

message BytesTypeInfo {
}

message DecimalTypeInfo {
}

message IntTypeInfo {
}

message StringTypeInfo {
}

message TimestampTypeInfo {
}

message VoidTypeInfo {
}

message ArrayTypeInfo {
  TypeInfo element_type = 1;
  repeated ArrayBoundaries dimension_boundaries = 2;
}

message ArrayBoundaries {
  int32 min = 1;
  int32 max = 2;
}

message CompositeTypeInfo {
  repeated FieldInfo components = 1;
}

message FieldInfo {
  string name = 1;
  TypeInfo type = 2;
}

message EitherTypeInfo {
    repeated FieldInfo options = 1;
}

message MapTypeInfo {
    TypeInfo key_type = 1;
    TypeInfo value_type = 2;
}

// Constraints

message Constraint {
    ConstraintType type = 1;
    string error_message = 2;
}
message ConstraintType {
    oneof kind {
        LengthConstraint length = 1;
        MaxDateConstraint max_date = 2;
        MinDateConstraint min_date = 3;
        MaxDecimalConstraint max_decimal = 4;
        MinDecimalConstraint min_decimal = 5;
        MaxIntConstraint max_int = 6;
        MinIntConstraint min_int = 7;
        MaxLengthConstraint max_length = 8;
        MinLengthConstraint min_length = 9;
        RegexConstraint regex = 10;
        RequiredConstraint required = 11;
        UniqueItemsConstraint unique_items = 12;
    }
}

message LengthConstraint {
  int32 length = 1;
}

message MaxDateConstraint {
  google.protobuf.Timestamp max = 1;
}

message MinDateConstraint {
  google.protobuf.Timestamp min = 1;
}

message MaxDecimalConstraint {
  common.BigDecimal max = 1;
}

message MinDecimalConstraint {
  common.BigDecimal min = 1;
}

message MaxIntConstraint {
  common.BigInt max = 1;
}

message MinIntConstraint {
  common.BigInt min = 1;
}

message MaxLengthConstraint {
  int32 max = 1;
}

message MinLengthConstraint {
  int32 min = 1;
}

message RegexConstraint {
  string regex = 1;
}

message RequiredConstraint {  
}

message UniqueItemsConstraint {
} 

Parameters

response of the parsing: Structured smart contract metadata

Invoke smart contract method

Request

Rest API: POST /api/smart-contracts//{smartContractId}/invoke gRPC API: swisschain.sirius.api.smart_contracts.SmartContracts.Invoke

POST /api/smart-contracts/{smartContractId}/invoke

> Request: (application/json, text/plain, */*)

x-request-id: 1a5c0b3d15494ec8a390fd3b22d757d6
x-tfa-code: 000000


document: "{\"methodName\":\"mint\",\"methodAddress\":\"40c10f19\",\"brokerAccountId\":100000074,\"arguments\":[{\"parameterName\":\"account\",\"value\":{\"prototype\":\"address\",\"address\":\"0x94afa005a395e470EB56a26E9081dC650EF84732\"}},{\"parameterName\":\"amount\",\"value\":{\"prototype\":\"int\",\"int\":100000000000000000}}],\"payment\":{\"assetId\":300000010,\"amount\":0}}"
signature: "JiOtcENJqblnWFcTZ4DiXwUZudlKBUtYnSkUjmfAH/8a1jeMPwFBu8MGjffITh3PRl/VLRTj8kjKWFT8EUR/8Qb3E8dTeuBlCIDU2RlHRRfb6iuTvjlPmUYQ/+Es6oZlH+Tapvjfa57N19poNZ7zimqadsASe3FGt0ME9J5vufE="



message SmartContractInvokeRequest {
  string request_id = 1;
  string document = 2;
  string signature = 3;
  int64 smart_contract_id = 4;
}


example:
{
  "request_id": "60f0cea8-1836-4ff5-b81d-422c1f705bce",
  "document": "{\"methodName\":\"mint\",\"methodAddress\":\"40c10f19\",\"brokerAccountId\":100000074,\"arguments\":[{\"parameterName\":\"account\",\"value\":{\"prototype\":\"address\",\"address\":\"0x94afa005a395e470EB56a26E9081dC650EF84732\"}},{\"parameterName\":\"amount\",\"value\":{\"prototype\":\"int\",\"int\":100000000000000000}}],\"payment\":{\"assetId\":300000010,\"amount\":0}}",
  "signature": "JiOtcENJqblnWFcTZ4DiXwUZudlKBUtYnSkUjmfAH/8a1jeMPwFBu8MGjffITh3PRl/VLRTj8kjKWFT8EUR/8Qb3E8dTeuBlCIDU2RlHRRfb6iuTvjlPmUYQ/+Es6oZlH+Tapvjfa57N19poNZ7zimqadsASe3FGt0ME9J5vufE=",
  "smart_contract_id": 109000043
}

Query Parameters

gRPC name type description example
smartContractId - string path
x-request-id - string header
x-2fa-code - string header
- request_id string -
document document optional, serialized-as-string, SmartContractInvocationDocument body
signature signature optional, string body
- smart_contract_id string -

Response

{
  "id": 110000034,
  "smartContractId": 109000043,
  "smartContractName": "goerlisec",
  "smartContractAddress": "0xa4c8d6d0f64965d3083137e2ab5eaa709f389089",
  "blockchainId": "ethereum-goerli",
  "blockchainName": "Ethereum Goerli",
  "methodName": "mint",
  "methodAddress": "40c10f19",
  "brokerAccountId": 100000074,
  "brokerAccountName": "SCV2New",
  "brokerAccountAddress": "0x94afa005a395e470EB56a26E9081dC650EF84732",
  "payment":
  {
    "assetId": 300000010,
    "amount": 0.0
  },
  "arguments":
  [
    {
      "parameterName": "account",
      "value":
      {
        "prototype": "address",
        "address": "0x94afa005a395e470EB56a26E9081dC650EF84732"
      }
    },
    {
      "parameterName": "amount",
      "value":
      {
        "prototype": "int",
        "int": 100000000000000
      }
    }
  ],
  "state": "processing",
  "invocationContext":
  {
    "document": "{\"methodName\":\"mint\",\"methodAddress\":\"40c10f19\",\"brokerAccountId\":100000074,\"referenceId\":\"example\",\"arguments\":
[{\"parameterName\":\"account\",\"value\":{\"prototype\":\"address\",\"address\":\"0x94afa005a395e470EB56a26E9081dC650EF84732\"}},{\"parameterName\":\"amount\",\"value\":{\"prototype\":\"int\",\"int\":100000000000000}}],\"payment\":{\"assetId\":300000010,\"amount\":0}}",
  "codeHash": "0x88604ca3b6d365a9bd9527be0065b6db",
  "referenceId": "example",
  "requestContext":
  {
    "userId": "0dde3a01-f675-439a-9439-0d1198ddaf8b",
    "ip": "10.244.4.0",
    "timestamp": "2021-12-10T05:51:54.1925873Z"
  }
  },
  "createdAt": "2021-12-10T05:51:54.5763207Z",
  "updatedAt": "2021-12-10T05:51:54.5763207Z"
  }
message SmartContractInvokeResponse {
  oneof result {
    SmartContractInvokeResponseBody body = 1;
    swisschain.sirius.api.common.ErrorResponseBody error = 2;
  }
}

message SmartContractInvokeResponseBody {
  SmartContractInvocation item = 1;
}

message SmartContractInvocation {
  enum SmartContractInvocationState{
    PROCESSING = 0;
    VALIDATING = 1;
    SIGNING = 2;
    SENT = 3;
    ON_CHAIN = 4;
    COMPLETED = 5;
    FAILED = 6;
    REJECTED = 7;
  }

  int64 id = 1;
  string tenant_id = 2;
  int64 smart_contract_id = 3;
  string smart_contract_name = 4;
  string smart_contract_address = 5;
  string blockchain_id = 6;
  string blockchain_name = 7;
  string method_name = 8;
  google.protobuf.StringValue method_address = 9;
  int64 invoker_broker_account_id = 10;
  string invoker_broker_account_name = 11;
  string invoker_broker_account_address = 12;
  int64 invoker_broker_account_details_id = 13;
  PaymentModel payment = 14;
  repeated smart_connect.data_model.Argument arguments = 15;
  SmartContractInvocationState state = 16;
  common.TransactionInfo transaction_info = 17;
  SmartContractInvocationContext invocation_context = 18;
  google.protobuf.Int64Value invocation_operation_id = 19;
  ValidatorContext validator_context = 20;
  int64 sequence = 21;
  SmartContractError error = 24;
  google.protobuf.Timestamp created_at = 22;
  google.protobuf.Timestamp updated_at = 23;
}


Parameters

POST /api/smart-contracts/{smartContractId}/invoke 200 OK GRPC swisschain.sirius.api.smart_contracts.SmartContracts.Invoke

Paginated response of the withdrawals update:

REST name gRPC name type description
id id number ID of the invocation
- tenant_id number address of the contract creator
smartContractId smart_contract_id number address of the contract creator
smartContractName smart_contract_name string Name of the smart contract
smartContractAddress smart_contract_address string address of the smart contract
blockchainId blockchain_id number Id of blockchain used for deployment
blockchainName blockchain_name string Name of blockchain used for deployment
methodName method_name string Name of method used for invocation
methodAddress method_address string Name of method used for invocation
brokerAccountId invoker_broker_account_id number ID of the broker account
brokerAccountName invoker_broker_account_name string Name of the broker account
- invoker_broker_account_details string Name of the broker account
payment payment PaymentModel details for payments executed during invocation
arguments arguments repeated smart_connect.data_model.Argument arguments used for deployment
state state string State of invocation
transactionInfo transaction_info string tx details like hash and confirmations count
invocationContext invocation_context string Details of initial invoke with document
validatorContext validator_context string Details of validator response
sequence sequence int update sequence
error error string Error details if transaction failed
createdAt created_at timestamp Datetime of invoke creation
updatedAt updated_at timestamp Datetime of last invoke update

Register known smart contract

Request

Rest API: POST /api/known-contracts/register gRPC API: swisschain.sirius.api.smart_contracts.SmartContracts.RegisterKnown

POST /api/known-contracts/register

> Request: (application/json, text/plain, */*)

X-Idempotency-ID: 1a5c0b3d15494ec8a390fd3b22d757d6
X-TFA-Code: 234567

{
  "familyCode": "CAST-Bond",
  "blockchainId": "ethereum-ropsten"
}


message RegisterKnownSmartContractRequest {
  string idempotency_id = 1;
  string tenant_id = 2;
  string family_code = 3;
  string blockchain_id = 4;
}

message RegisterKnownSmartContractResponse {
  oneof kind {
    RegisterKnownSmartContractPayload payload = 1;
    RegisterKnownContractError error = 2;
  }
}

message RegisterKnownSmartContractPayload {
  int64 id = 1;
}

message RegisterKnownContractError {
  enum ErrorCode {
    UNKNOWN = 0;
    INVALID_PARAMETERS = 1;
    DOMAIN_PROBLEM = 2;
    TECHNICAL_PROBLEM = 3;
    NOT_AUTHORIZED = 4;
  }

  ErrorCode code = 1;
  string message = 2;
}


example:
{
  "idempotency_id": "60f0cea8-1836-4ff5-b81d-422c1f705bce",
  "tenant_id": "1960bc2f-884b-43a4-bf4a-8a9163fb4807"
  "family_code": "CAST-Bond",
  "blockchain_id": "ethereum-ropsten"
}

Query Parameters

REST name gRPC name type REST placement description
X-idempotency-ID - string header Unique ID of the request
- idempotency_id string - Unique ID of the request
family_code family_code string body short codename of a known smart contract family
blockchain_id blockchain_id string body ID of target blockchain
tenant_id tenant_id string JWT token claim ID of tenant

Response

{
  "id": 130000004
}

Parameters

Response:

REST name gRPC name type description
id id number ID of the known contract registration

Data structures

Order (enum)

Order of the sorting

NetworkType (enum)

Type of blockchain network

BlockchainProtocol (object)

TagType (enum)

Tag type of the account. Tag is additional information associated with particular account, which can be specified in the blockchain transaction. This allows to use single blockchain address to handle many accounts on it. This feature is available only on some blockchains: (Ripple, Stellar, Eos...). In some blockchains different types of the tag are supported, and you have to specify exact type in this case.

DoubleSpendingProtectionType (enum)

Each blockchain uses some protection mechanism against funds double-spending. Sirius distinguishes the following types:

BrokerAccountState (enum)

State of the broker account

AccountState (enum)

State of the account

CustodyType (enum)

Type of the vault

DepositState (enum)

State of the deposit

DepositType (enum)

Type of the deposit

BrokerAccountDetails (object)

Details of the broker account

BrokerAccountDetailsBrief (object)

Brief broker account details

AccountDetails (object)

Details of the account

AccountDetailsBrief (object)

Brief details of the account

BrokerAccountBalances (object)

Balances of the broker account in a particular asset. We distinguish 4 different balances for each asset in each broker account.

DestinationDetails (object)

Destination details for a transfer

WithdrawalDocument (object)

TransactionInfo (object)

TransactionInfo contains information about the transaction which happened on the blockchain.

DepositSource (object)

DepositSource indicates from which address amount came form.

AmlChecks (object)

AmlChecks contains information about passed AML checks for deposit.

CompletedAmlCheck (object)

CompletedAmlCheck contains information about passed AML check for deposit.

AmlOverallResolution (enum)

AmlResolution (enum)

WithdrawalState (enum)

WithdrawalError (enum)

SmartContractDeploymentDocument (object)

SmartContractInvocationDocument (object)

DataItem