Getting Started with the API

15 min

Introduction

The proprietary Custody Infrastructure Python SDK/API client, provided to customers, integrates the customers’ core business systems with Custody Infrastructure platform. The SDK communicates with the cloud mandatory cosigner (MCS) and allows actions to be automated from the customer's mobile or desktop apps.

Contact support for information about installing and accessing the developer backend for the first time.

Architecture and Interfaces

The below scheme describes the system's interfaces. Custody Infrastructure provides branded desktop and mobile apps as part of the delivery, as well as an SDK/API package. The Mandatory Cosigner can run either on the cloud or on-premises in an environment provided by the client.

Custody Infrastructure system architecture

The applications provided bring Custody Infrastructure's solution to:

Android 8 and above (recommended version 13 or above)

iOS 15 and above (iPhone Minis are NOT supported)

MacOS Monterey and above (both Intel and M1-2)

Windows 8 and above

Galaxy's Custody Infrastructure provides an SDK including a Python API client that can be used to operate your Custody Infrastructure deployment alongside or instead of the desktop and mobile applications.

The API provides various categories of calls, enabling:

Trading

Staking

Running smart contracts

Coins Management

Accounts Management

Wallets Management

Cashbox Management

Setting system preferences

...as well as other operations.

As every call requires providing authentication from your client to the server, every call is technically a POST call. Even a simple request for information, to be secure, uses the POST method.

Requirements

The API will not function when accessed from a mobile device.

Our system has been thoroughly tested with the dependency versions listed below to ensure optimal performance. If you'd like to use a different version, our friendly support team is here to help you explore your options!

Dependency	Version
Python	3.10
aiohttp	3.10.8
bech32	1.2.0
bip32	3.4
bitcoin-utils	0.6.8
cashaddress	1.0.6
cryptography	43.0.3
connexion	2.14.2
cachetools	5.5.0
ECPy	1.2.5
pycryptodome	3.21.0
pycryptodomex	3.21.0
python-dateutil	2.9.0.post0
stellar_sdk	11.0.0
tinyec	0.4.0
qrcode	7.4.2
fastecdsa	2.2.3
eth_abi	5.1.0
websockets	13.0.1
websocket-client	1.7.0
websocket-server	0.6.4
starknet-py	0.23.0
appdirs	1.4.4
Flask-Cors	5.0.0

Configuring a Testnet User

To create a Mainnet API user, see Creating a Mainnet API User from the Desktop App or Cold Vault.

After initial SDK installation, a user must be created to access the API system. That user's information is then added into the environment the user will be using to make API calls. Your system can support any number of API users, but it is easiest to have each user use their own environment for working with the API.

Best practice is to give the API user a distinct name. This makes it easier to identify what actions originated from API calls when performing an audit.

Security Note

You will be asked to convert a QR code to text and save the results later in this process.

!!!KEEP THE CODE AND TEXT SECURE AND CONFIDENTIAL!!!

The QR code contains your:

shared secret

user private key

user public key

server ip address

api keys

user identifier

user name

server identifier

Your account can be compromised if this information falls into the wrong hands.

Creating a New API User - Phase One: The Cold Vault

Before beginning, have your mobile phone ready.

Before adding a new user, ensure the following are present in the room with the cold vault:

A system admin

The prospective user

Device capable of scanning a QR code and saving the resulting .txt file

Adding a non-admin new user

If the environment is in MPC Driven mode, you can create the API user on either the MPC or Cold Vault. In the testnet environments, the API user can only be created locally on the Cold Vault. The example below will demonstrate using the Cold Vault, as it works for both modes.

Click Add new user on the Cold Vault's Administration Sidebar to get to the 'User setup' window.

The User Setup popup

Input the first and last name to represent the user. We recommend including "API" somewhere in the user's name.

Input the user's email address.

Select MPC User.

As the Cold vault is not able to receive any communication from the network, it cannot be interacted with via the API. There's no need for an API user to have cold vault access.

Click OK.

Create

Select Scan a QR Code then click Get a QR Code.

After requesting a QR code, a warning screen appears.

The screen prior to the first QR code

After pressing CONFIRM, the user is prompted to register their Galaxy Custody app.

During this next part of the process, the system will display two QR codes, one after the other.

There is no need to use the Galaxy Custody Mobile app in this process. Just scan the QR code with any QR to text scanner.

Click Register to Cold. The system displays the first QR code.

Scan the QR code with your mobile phone's camera or a QR code to text application. Save the resulting text securely. It can be used against you.

Click Next.

A new QR code pops up. "111111" is automatically populated. Click Authenticate.

The new user is added to the table of users after completion of the configured approval flow. You now have all the information you need to use the API as the newly configured user, but the user needs to first be configured on the system.

Setup of a New API User

The default group (unassigned group) and role of a new user must be updated. Until properly configured, a new API user cannot initiate any transactions. Edit the user via the User Management page. First, assign the user an appropriate role.

API calls are subject to the role and permissions of the user making them. A user is still bound by their limits when using the API.

After the user's role and permissions are configured, use the pencil icon on the User Table to open the API user's Update User panel. Click the three vertical dots, then select Reactivate API Access. Run through the system approval process if needed.

The user is now ready to be configured in the API file.

Creating a New API User - Phase Two: The Client Machine

API calls are made from the user's client computer to the API server running on the Mandatory Cosigner (MCS).

Prerequisites

The SDK and all dependencies are installed

A user is configured on the Cold Vault

You have the text rendition of the user's QR code

You know the IP address of your MCS

Preparing the environment

First, import the SDK files into your working environment.

import json
import random
import uuid
import sys
import time
from typing import Optional

import ecdsa.util
from Collector import CollectorConfig, CollectorType
from ApiClient import ApiClient
from Helpers.ApiClientPool import ApiClientPool
from Helpers.helpers import getInfoFromQr
from MpcDriven.Action import Action, ActionType
from MpcDriven.AdministrativeApprovalData import AdministrativeApprovalData
from MpcDriven.Contact import Contact, AuthorizationType
from MpcDriven.RequestExtraData import RequestExtraData
from MpcDriven.UserRole import UserRole
from MpcDriven.EnumTypes import SignatureType, AccountSelectionMode
from MpcDriven.AccountInfo import AccountInfo, AccountType
from MpcDriven.TransactionPolicy import DestinationInfo, TransactionPolicy, TransactionPolicyType, \
    TransactionPolicyRange, RoleIdsToWorkflowIds

Create a .txt file containing the text from your qr code.

Call ApiClient.fromQr(path_to_your_qr, MCS_IP_ADDRESS) Replace path_to_your_qr with the path to the .txt file you created earlier. Replace MCS_IP_ADDRESS with the IP Address of the MCS.

This creates the initial instance of your API user.

Once your user is instantiated, your SDK environment can be used to make calls to the Custody Infrastructure API.

Your user is created with unique access tokens encoded to your qr code information. Each call you make requires one access token, but the response you receive includes a new token. Each token can be used once.