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!

V2 requests signing

V2 API supports signed requests with asymmetric cryptography. Since every type of request is structurally different, the format of the data to be signed also varies. In order to sign a request, clientside has to put together a string in the specific format and sign that string with the customer's private key, thereby generating RSA signature. Every V2 API definition contains special-purpose optional field called "Signature", which has to be used to pass the RSA signature to the serverside.

The specific formats of the data to be signed are defined on the respective pages, describing an API endpoint. For clarity, each API endpoint page contains subsection called "Signing data format" with detailed description of the parameters to be used for putting together textual data for signing.

For convenience of use, links to all formats' descriptions are compiled below:

• Withdrawal V2 execution signing data format

Signing format guidelines

While all requests serve various purposes and therefore consist of different parameters, they also follow several common patterns. The way some of these patterns are used across V2 APIs in relation to the signing functionality is described below:

General format description

Signing data is a sequence of bytes, corresponding to UTF-8-encoded string in the specific format. The beginning and ending of the signing data are denoted by square brackets: []. Each parameter value is encased in single quotes: ''. Parameters are comma-separated without any whitespace characters before or after the separator. In the example below there are three parameters, two textual ones and a single numeric parameter:

['parameter Value 1','parameter Value 2','26.7']

Complex parameter values

Complex parameter values such as hashmaps or collections are represented as a single parameter encased with single quotes, in which several chunks of data may appear separated by a semicolon (;). In the example below there are two parameters, first one representing a collection of values and second one is a hashmap:

['1.2;34.0;123.1;12.0','keyOne:valueOne;keyTwo:valueTwo']

Argument parameter values

The arguments in the signing data represent inputs to the smart contract method being invoked. Similar to complex parameters, smart contract argument parameter values are represented as a single parameter encased with single quotes. Each Argument object consists of a parameter name and its corresponding value, and these are separated by a colon (:).

The Argument objects are sorted alphabetically by their parameter names. They are then appended to the signing data format string, with each Argument object separated by a semicolon (;).

Different types of arguments are formatted as follows:

Void: A void argument type doesn't have a value to be represented, so the value should not appear in the signing data. Example: 'voidParameterName:'

Bool: A boolean argument is represented as either true or false. Example: 'flag:true'

Bytes: Byte array arguments are Base64-encoded. Example: 'byteArray:SGVsbG8='

This is for the byte array equivalent of the string "Hello".

Decimal: A BigDecimal argument is formatted with at least one fractional digit, even if the value is an integer. Example: 'decimalValue:2.0'

Int: A BigInteger argument is represented as is. Example: 'intValue:123'

String: String arguments are formatted in the same way as string parameters, i.e. with special characters escaped. Example: 'stringValue:Hello\:world'

Address: Ethereum address arguments are represented as is. Example: 'address:0x663e933ECdc5b1acbaCB87F4aa1636cd05837613'

Timestamp: A timestamp argument is represented in the same format it was passed to the API originally, following RFC 3339 format used in google.protobuf.Timestamp, i.e. {year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z. Example: 'timestampParam:2017-01-15T01:30:15.01Z''

Enum: An enumeration argument is represented as a string. Example: 'enumValue:OPTION_ONE'

Array: Array arguments are formatted as a string with elements separated by a semicolon (;). Example: 'arrayArg:{value1;1234}'

Composite: Composite arguments are objects that contain fields. These fields are sorted alphabetically by name and formatted as a string of key-value pairs. Example: 'composite:{'field1':'value1','field2':'value2'}'

Map: Map arguments are formatted as a string with entries separated by a semicolon. Each entry is formatted as a key-value pair with a colon separating the key from the value. Example: 'arg1:{mapKeyB:mapValueB;mapKeyA:mapValueA}' NB: map arguments ARE NOT sorted alphabetically by the keys, since the keys can theoretically be of different type, including complex ones. Since it is not feasible to compare for instance an array with a timestamp for the purpose of sorting them, it was decided to format map arguments in the order they were provided.

Either: An either argument can have one of two possible types. The value is formatted based on its actual type (as described above). The argument name indicates which type it is. Example: 'arg1:{field1:value1}'

If the list of Argument objects is empty or null, it should be represented as null without quotes.

The arguments' values have to be formatted correctly based on their types. For instance, if the value is a BigDecimal, it is important to ensure that there's at least one fractional digit. If it's a String, the special characters have to be escaped. In case of complex types like Array, Composite, or Either, the elements inside are sorted alphabetically by their keys before they are formatted for signing. However, the complex type of Map does not require sorting and it the signing data will be constructed in the original order of key-value pairs of map.

In the case where Argument objects contain complex parameter values like Array, Map, Composite, or Either, each value is formatted and encased in curly brackets {}. Each value inside these complex types is separated by a semicolon (;), and in the case of Map, Composite and Either, each key-value pair is separated by a colon (:).

Special characters

Since original parameter values may contain special characters, used to encase values or denote boundaries between chunks of data, their values have to be escaped with a backslash (\). The comprehensive list of special characters is defined below: - : separates key and its corresponding value in hashmaps, escaped as \: - ; separates key-value pairs in hashmaps and values in collections, escaped as \; - ' encases parameter values, escaped as \' - \ used to escape special characters, escaped as \\

In the example below there are several parameters with special characters in their original values:

['Ocean\'s eleven','keyOne:value\:One;key\;Two:valueTwo','\\path\\to\\directory\\targetFile.txt']

Empty and unset values

Some parameters are optional, but since their position in the signing data format is rigid, it is not possible to simply omit them. Instead, the absence of its value has to be denoted explicitly with null without quotes. In the example below there are two parameters, the first one with value and the second one with value unset:

['Parameter Value One',null]

The absence of a complex parameter value (i.e. when a hashmap parameter is unset) should be treated in the same way.

Numeric values

Numeric parameters, specifically those with data types that can contain a fractional part (such as decimal, double, float, etc.), must be formatted with at least one decimal digit, regardless of whether they have a fractional part or not. These parameters often represent quantities, such as asset amounts.

For example, a decimal value of 2 should be represented as 2.0 in the signing data:

['2.0']

This rule ensures consistency in how numeric values are presented in the signing data.

On the other hand, numeric data types that do not support a fractional part (e.g., integer, long, short, etc.) must be formatted without a fractional part and without a decimal separator symbol. For instance, an integer value of 2 should remain as 2 in the signing data:

['2']

It's important to distinguish between these two cases to prevent any ambiguity when processing the signing data.

Configurable properties

Most API V2 requests support assigning custom properties in the form of set of key-value pairs. Since assigning properties can change the way request will be handled on the serverside (see known properties), properties are included in the signing data. Properties normally appear at the very end of signing data format as a single parameter, encased in single quotes ('). Properties data is concatenated without any whitespace characters with colon (:) as a separator between a key and its corresponding value, and semicolon (;) as a separator between key-value pairs. In the signing data format order of properties is important. It is required to sort them alphabetically by keys.

In the example below there are two regular parameters, followed by four custom properties, sorted by keys alphabetically:

['parameter Value One','124662357832','BrokerageExternalId:445566778899;UserId:12345;UserValidatorId:dr3413;WalletName:TestWallet']

V2 APIs normally accept properties as a hashmap, with key-value pairs in arbitrary order. Received pairs of properties will be sorted during signature validation internally on the serverside. Following this logic, properties from the example above can be sent to the serverside in the following way: json { "properties": { "UserValidatorId": "dr3413", "WalletName": "TestWallet", "BrokerageExternalId": "445566778899", "UserId": 12345 } }

If the properties are not present at all, it is required to denote their absence with null similar to any other parameter.

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. The asset is a generic model which represents a native asset, fungible token or a non-fungible token. 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. 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.

Rest API: /api/v2/assets

gRPC API: swisschain.sirius.api.v2.assets

Search

Returns assets by search parameters.

gRPC API example: ```csharp var request = new AssetSearchRequest { Id = 10001, BlockchainId = "ethereum", Symbol = "USDC", TokenId = null, Address = "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", Accuracy = 6, Pagination = new PaginationInt64 { Cursor = null, Limit = 100, Order = PaginationOrder.Asc } };

var response = client.AssetsV2.SearchAsync(request); ```

REST API example: json GET /api/v2/assets?blockchainId=bitcoin&symbol=BTC

Request

Response

Paginated array of the assets.

AddAttributes

Adds asset attributes.

gRPC API example: ```csharp var request = new AssetAddAttributesRequest { IdempotencyId = "AD1D5199-1D1F-4B2C-AE6C-DED0DAAC4D34", AssetId = 10001, Aml = new AmlAssetAttributesCreateInfo { Chainalysis = new AmlChainalysisAssetAttributesInfo { Symbol = "USDC", TransferFormat = ChainalysisTransferFormat.HashAndAddress, IsCheckDepositsEnabled = true, IsCheckWithdrawalsEnabled = true, IsNotifyWithdrawalsEnabled = true }, MerkleScience = new AmlMerkleScienceAssetAttributesInfo { Symbol = "USDC", Currency = 14, IsDisabled = false } }, Brokerage = new BrokerageAssetAttributesCreateInfo { MinDepositThreshold = 1, MinWithdrawalAmount = 1 } };

var response = client.AssetsV2.AddAttributes(request); ```

REST API example: ```json POST /api/v2/assets

Request: (application/json)

Headers:
X-Idempotency-ID: AD1D5199-1D1F-4B2C-AE6C-DED0DAAC4D34

Body: { "assetId":123122, "brokerage":{ "minDepositThreshold":9, "minWithdrawalAmount":144 }, "aml":{ "chainalysis":{ "symbol":"MANA", "isCheckWithdrawalsEnabled":true, "isCheckDepositsEnabled":true, "isNotifyWithdrawalsEnabled":true, "transferFormat":"hashAndIndex" }, "merkleScience":{ "symbol":"MANA", "currency":3, "isDisabled":true } } } ```

Request

Response

Models

Asset

AmlAssetAttributesCreateInfo

AmlAssetAttributesInfo

AmlChainalysisAssetAttributesInfo

ChainalysisTransferFormat (enum)

• HashAndIndex - Hash and index
• HashAndAddress - Hash and address
• Hash - Hash

AmlMerkleScienceAssetAttributesInfo

BrokerageAssetAttributesCreateInfo

BrokerageAssetAttributesInfo

Data structures

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.

• text - text tag
• number - numeric tag

WithdrawalDocument (object)

• properties (map) set of key-value pairs containing custom or known properties
• assetId (number) - ID of the asset to use
• brokerAccountId (number) - ID of the broker account to use
• destinationDetails (DestinationDetails) - Destination details
• amount (decimal) - Withdrawal amount

DestinationDetails (object)

• address (string) withdrawal destination address
• destinationTag (DestinationTag) - destination tag value and type

DestinationTag (object)

• value (string optional) string value of the tag
• tagType (TagType) - type of the tag to use

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:

• You can pull withdrawals updates REST API
• You can listen for withdrawal updates gRPC stream
• You can register a web-hook to get the notifications

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. You can provide "WalletId" property with the value of account reference ID in order 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. Also you can provide "UserId" property with the value of UserNativeId in the users dictionary. This association is optional and can be used to enable AML verification procedure.

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

The lifecycle of a withdrawal:

Starts a withdrawal

Request

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

POST /api/v2/withdrawals

> Request: (application/json)

X-Idempotency-ID: 36585f34-d311-433a-87f1-1751b08480c3
X-TFA-code: 785441

{
  "document":{
    "properties":{
      "WalletId":"12345",
      "UserId":"test"
    },
    "assetId":300578305,
    "brokerAccountId":100000140,
    "destinationDetails":{
      "address":"0x663e933ECdc5b1acbaCB87F4aa1636cd05837613"
    },
    "amount":0.1,
    "feePayer":"sender"
  },
  "signature":"pqG0st53GVkdBHIqCHsg9cB4noO1nyXlM8UGkZ+bC0fmvCbuf0W78GYj8ZuCtPMWl0XDIh5hVjwsjIPhiUfCl5KVUIA8La3EunRJZ5UkW95IvjcPCn+z5atzb8JQxPee8q2ehaMY+UNH08p1VmIjqJE1eKFzzs8ZxITu0gtwbZ4="
}

swisschain.sirius.api.v2.withdrawals.Execute

> Requests: (application/grpc)

message WithdrawalExecuteRequest {
  string idempotency_id = 1; // '36585f34-d311-433a-87f1-1751b08480c3'
  WithdrawalDocument document = 2;
  bytes signature = 3; // a6 a1 b4 b2 de 77 19 59 1d 04 72 2a 08 7b 20 f5 c0 78 9e 83 b5 9f 25 e5 33 c5 06 91 9f 9b 0b 47 e6 bc 26 ee 7f 45 bb f0 66 23 f1 9b 82 b4 f3 16 97 45 c3 22 1e 61 56 3c 2c 8c 83 e1 89 47 c2 97 92 95 50 80 3c 2d ad c4 ba 74 49 67 95 24 5b de 48 be 37 0f 0a 7f b3 e5 ab 73 6f c2 50 c4 f7 9e f2 ad 9e 85 a3 18 f9 43 47 d3 ca 75 56 62 23 a8 91 35 78 a1 73 ce cf 19 c4 84 ee d2 0b 70 6d 9e
}

message WithdrawalDocument {
  map<string,string> properties = 1; // { "WalletId":"12345", "UserId":"test" }
  int64 asset_id = 2; // 300578305
  int64 broker_account_id = 3; // 100000140
  DestinationDetails destination_details = 4;
  swisschain.sirius.api.common.BigDecimal amount = 5; // 0.1
  swisschain.sirius.api.common.FeePayer fee_payer = 6;
}

message DestinationDetails {
  string address = 1; // "0x663e933ECdc5b1acbaCB87F4aa1636cd05837613"
  DestinationTag destination_tag = 2; // null
}

message DestinationTag {
  google.protobuf.StringValue value = 2;
  swisschain.sirius.api.common.TagType type = 3;
}

Parameters

Signing data format

Withdrawal signing data format (order of parameters is important): ['36585f34-d311-433a-87f1-1751b08480c3','300578305','100000140','0x663e933ECdc5b1acbaCB87F4aa1636cd05837613',null,null,'0.1','sender','UserId:test;WalletId:12345']

Parameters used: 0: IdempotencyId 36585f34-d311-433a-87f1-1751b08480c3

1: AssetId 300578305 (BNB)

2: BrokerAccountId 100000140

3: DestinationAddress 0x663e933ECdc5b1acbaCB87F4aa1636cd05837613

4: DestinationTag null

5: DestinationTagType null

6: Amount: 0.1 7: FeePayer: sender

8: Properties:

8.1: UserId: test (corresponds to UserNativeId)

8.2: WalletId: 12345 (corresponds to AccountReferenceId)

When putting together signing data, it is required to sort properties alphabetically by keys. However, gRPC and REST APIs accept properties as hashmap of unordered key-value pairs. These key-value pairs will be sorted during signature validation internally on the serverside.

The presented signing data format is used whenever client wishes to execute signed withdrawal. Withdrawal signing data has to be constructed on the client side and signed with customer private key.

Notes on the signing data format: - Please use null without quotes for parameters without value (including properties) - Please format numeric values with at least one fractional digit, even if the value is an integer (i.e. 2 has to become 2.0)

For more information on the signing data format and its usage please refer to the page dedicated to signing data formats.

Response

POST /api/v2/withdrawals

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

{
 "id":106000003
}

swisschain.sirius.api.withdrawals.Withdrawals.Execute

> Response: (application/grpc) - success response

message WithdrawalExecutePayload {
  int64 id = 1;
}

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

  ErrorCode code = 1;
  string message = 2;
}

message WithdrawalExecuteResponse {
  oneof result {
    WithdrawalExecutePayload payload = 1;
    WithdrawalExecuteError error = 2;
  }
}

Parameters

SmartContracts

Invoke smart contract method

Request

Rest API: POST /api/v2/smart-contracts/{smartContractId}/invoke gRPC API: Swisschain.Sirius.Api.ApiContract.V2.SmartContracts.Invoke

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

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

x-idempotency-id: 1a5c0b3d15494ec8a390fd3b22d757d6

{
  "Document": {
    "Properties": {
      "prop1": "value1",
      "prop2": "value2"
  },
  "MethodName": "mint",
  "MethodAddress": "40c10f19",
  "BrokerAccountId": 100000074,
  "ReferenceId": "1a5c0b3d15494ec8a390fd3b22d757d6",
  "Arguments": [
    {
      "ParameterName": "account",
      "Value": {
        "Prototype": "address",
        "Address": "0x94afa005a395e470EB56a26E9081dC650EF84732"
      }
    },
    {
      "ParameterName": "amount",
      "Value": {
        "Prototype": "int",
        "Int": 100000000000000000
      }
    }
  ],
  "Payment": {
    "AssetId": 300000010,
    "Amount": 0
  }
  },
  "Name": "MyContractInvocation",
  "Signature": "JiOtcENJqblnWFcTZ4DiXwUZudlKBUtYnSkUjmfAH/8a1jeMPwFBu8MGjffITh3PRl/VLRTj8kjKWFT8EUR/8Qb3E8dTeuBlCIDU2RlHRRfb6iuTvjlPmUYQ/+Es6oZlH+Tapvjfa57N19poNZ7zimqadsASe3FGt0ME9J5vufE="
}

message SmartContractInvokeRequest {
  string idempotency_id = 1;
  SmartContractInvocationDocument document = 2;
  bytes signature = 3;
  int64 smart_contract_id = 4;
  string name = 5;
}

message SmartContractInvocationDocument {
  int64 broker_account_id = 1;
  string method_name = 2;
  google.protobuf.StringValue method_address = 3;
  repeated swisschain.sirius.api.smart_connect.data_model.Argument arguments = 4;
  swisschain.sirius.api.smart_contracts.common.Payment payment = 5;
  google.protobuf.StringValue reference_id = 6;
  map<string,string> properties = 7;
}


// example:
{
  "idempotency_id": "60f0cea8-1836-4ff5-b81d-422c1f705bce",
  "document": {
    "broker_account_id": 100000074,
    "method_name": "mint",
    "method_address": "40c10f19",
    "arguments": [
      {
        "parameterName": "account",
        "value": {
          "prototype": "address",
          "address": "0x94afa005a395e470EB56a26E9081dC650EF84732"
        }
      },
      {
        "parameterName": "amount",
        "value": {
          "prototype": "int",
          "int": 100000000000000000
        }
      }
    ],
    "payment": {
      "assetId": 300000010,
      "amount": 0
    },
    "reference_id": "1234",
    "properties": {
      "exampleKey": "exampleValue"
    }
  },
  "signature": "JiOtcENJqblnWFcTZ4DiXwUZudlKBUtYnSkUjmfAH/8a1jeMPwFBu8MGjffITh3PRl/VLRTj8kjKWFT8EUR/8Qb3E8dTeuBlCIDU2RlHRRfb6iuTvjlPmUYQ/+Es6oZlH+Tapvjfa57N19poNZ7zimqadsASe3FGt0ME9J5vufE=",
  "smart_contract_id": 109000043,
  "name": "ExampleName"
}

Query Parameters

Response

{
  "SmartContractInvocationId": 123456789
}

message SmartContractInvokeResponse {
  oneof kind {
    SmartContractInvokePayload payload = 0;
    SmartContractInvokeError error = 1;
  }
}

message SmartContractInvokePayload {
  int63 id = 1;
}

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

  ErrorCode code = 0;
  string message = 1;
}

Signing data format

Smart Contract Invocation V2 signing data format (order of parameters is important):

Parameters used:

0: IdempotencyId `422895a404f220d08763`

1: MethodName `createForgeBond`

2: MethodAddress `0x6ff569ba`

3: BrokerAccountId `100000077`

4: ReferenceId `null`

5: Arguments `basicTokenInput:{...};registryAddress:0x99b7a5170d2F89bB22a295DE41B548eB4A345bc0`

6: AssetId `300638515`

7: PaymentAmount `0.0`

8: Properties `CastOperationType:Issuance;FactoryAddress:0xAd3df4b196d2fbafecd6CFa6914B73d2d5812da3;...`

When constructing the signing data, ensure the properties are sorted alphabetically by keys. Despite gRPC and REST APIs accepting properties as a hashmap of unordered key-value pairs, these pairs will be internally sorted during signature validation on the server-side.

This signing data format is used whenever a client wishes to execute a signed Smart Contract Invocation V2. The signing data must be created on the client side and signed with the customer's private key.

Notes on the signing data format:

- Please use `null` without quotes for parameters without value (including properties)
- Please format numeric values according to their type. Numeric data types that can contain a fractional part (e.g., decimal, double, float, etc.) must be formatted with at least one decimal digit. Numeric data types that cannot contain a fractional part (e.g., integer, long, short) must be formatted without a fractional part and without a decimal separator.

For more information on the signing data format and its usage, please refer to the page dedicated to *[signing data formats](_signing-data.md)*.

Known properties

V2 API allows assigning custom properties to some requests in the form of set of key-value pairs where both key and value are strings. Users can provide custom keys or use some known properties with predefined behaviour and functionality.

The list of the known properties and their respective behaviour is defined below:

1. UserId: allows passing identifier from the AML verification (formerly known as UserNativeID);
2. WalletId: allows linking request to specific account, the value is used to look up Account with the specified AccountReferenceId