This document outlines the required steps to integrate with Zodia using our API.
Document created on April 20th, 2021. Last updated on February 4th, 2023.

Contact: customerservice@zodia.io

Decommissioning of V1.

• Zodia's API is RESTful over HTTPS and consumes JSON payload
• Transport level security is TLS 1.2.
• Requests must be digitally signed using SHA256withRSA (minimum 2048 bits)
• Zodia's API requires at least two users: a maker (creation request) and a checker (approval request)
• The examples below in Python require the libraries:
  • cryptography that can be installed with pip: pip install cryptography
  • requests that can be installed with pip: pip install requests

Before invoking Zodia's API, your company's account must be set up onto Zodia by Zodia's staff.
To complete this setup, your company must generate a key pair. We will refer to these keys as:

• company_pri_key for the private key
• company_pub_key for the public key

Those keys must be RSA keys (encoded in base 64) with a minimum size of 2048 bits.
Once generated, your company must share the public key company_pub_key with Zodia's staff: customerservice@zodia.io

WARNING: You must never share the private key company_pri_key with anyone including Zodia staff. This private key must be stored securely

How to generate keys for a company

Below is an example of how to generate a key pair for the company named ZTEST:

import os
from cryptography.hazmat.backends import default_backend
from cryptography.hazmat.primitives import serialization
from cryptography.hazmat.primitives.asymmetric import rsa

def generate_rsa_keypair(company):
    rsa_private_key = rsa.generate_private_key(public_exponent=65537, key_size=2048, backend=default_backend())
    private_key_pem = rsa_private_key.private_bytes(serialization.Encoding.PEM,
                                                serialization.PrivateFormat.PKCS8,
                                                serialization.NoEncryption())
    with open(os.path.join("keys", company + ".private.pem"), "wb") as private_key_out:
        private_key_out.write(private_key_pem)
        
    rsa_public_key = rsa_private_key.public_key()
    public_key_pem = rsa_public_key.public_bytes(serialization.Encoding.PEM,
                                              serialization.PublicFormat.SubjectPublicKeyInfo)
    with open(os.path.join("keys", company + ".public.pem"), "wb") as public_key_out:
        public_key_out.write(public_key_pem)

if __name__ == '__main__':
    generate_rsa_keypair("ZTEST")
    # Private key "company_pri_key" can be found in the file "ZTEST.private.pem"
    # Public key "company_pub_key" can be found in the file "ZTEST.public.pem"

At least two API users must be added to your company's account.

Important note

If the company has already been set up as explained above in the document, then Zodia customer service cannot create any API accounts on the created company. Only your company user maker will be able to create these two required API accounts.
However, if the company has not already been set up on Zodia UI, then Zodia onboarding team can create the company with the two required API accounts. Other user accounts can also be created by Zodia team at the time of the new company creation.

By convention, the API users should have an id starting with api-. Examples: api-maker and api-checker
To onboard these users, you must generate a key pair for each API user. We will refer to these keys as:

• api_user_pri_key for the private key
• api_user_pub_key for the public key

Each API user is composed of three pieces of information:

• an api user email (just an identifier)
• an Elliptic Curve public key (encoded in base 64)
• an api user id which is the concatenation of the api user email with the first 10 letters of the hexadecimal representation of the hash (SHA256) of the public key.

These 3 pieces of information must then be shared with Zodia's staff: customerservice@zodia.io

Applying the two "How-to" steps below results in the following example:

• api user email: api-maker@zodia.io
• api user id: api-maker@zodia.io::76b728bb89
• public key: MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEeo/e0vtlHo44xeAOvDxZtlmnyKgkQrvoq/M2kpawqGOO+7FrUPktZm+wxqzE/Etta5F8sewpqYK5RgCbXtplSA==

WARNING: You must never share the private key api_user_pri_key with anyone including Zodia staff. This private key must be stored securely

How to generate keys for an API user

Please note that the Elliptic Curve that must be used to generate those keys is SECP256R1
Below is an example of how to generate a key pair for the user whose email is api-maker@zodia.io:

import os
from cryptography.hazmat.backends import default_backend
from cryptography.hazmat.primitives import serialization
from cryptography.hazmat.primitives.asymmetric import ec

def generate_ec_keypair(user):
    ec_private_key = ec.generate_private_key(ec.SECP256R1(), default_backend())
    private_key_pem = ec_private_key.private_bytes(serialization.Encoding.PEM,
                                                serialization.PrivateFormat.PKCS8,
                                                serialization.NoEncryption())
    with open(os.path.join("keys", user + ".private.pem"), "wb") as private_key_out:
        private_key_out.write(private_key_pem)
        
    ec_public_key = ec_private_key.public_key()
    public_key_pem = ec_public_key.public_bytes(serialization.Encoding.PEM,
                                              serialization.PublicFormat.SubjectPublicKeyInfo)
    with open(os.path.join("keys", user + ".public.pem"), "wb") as public_key_out:
        public_key_out.write(public_key_pem)

if __name__ == "__main__":
    generate_ec_keypair("[email protected]")
    # Private key "api_user_pri_key" can be found in the file "[email protected]"
    # Private key "api_user_pub_key" can be found in the file "[email protected]"

How to generate user id for an API user

Once you have the public key of the API user, you can generate the api user id by doing:

import os, binascii
from cryptography.hazmat.backends import default_backend
from cryptography.hazmat.primitives import hashes, serialization

def generate_zodia_user_id(user):
    with open(os.path.join("keys", user + ".public.pem"), "rb") as public_key_in:
        ec_public_key = serialization.load_pem_public_key(public_key_in.read(), backend=default_backend())

    public_key_bytes = ec_public_key.public_bytes(serialization.Encoding.DER,
                                                  serialization.PublicFormat.SubjectPublicKeyInfo)
    digest = hashes.Hash(hashes.SHA256(), backend=default_backend())
    digest.update(public_key_bytes)
    sha256 = digest.finalize()
    hex_id = binascii.hexlify(sha256).decode('UTF-8')
    return user + "::" + hex_id[-10:]

if __name__ == "__main__":
    zodia_user_id = generate_zodia_user_id("[email protected]")
    print(zodia_user_id)  # [email protected]::76b728bb89

In order to provide a high-quality service, Zodia's API is rate limited. The default limits are:

• 1 request per second per endpoint
• 128 requests per day per endpoint

Please reach out to Zodia if you wish to adjust the rate limit for given endpoints.
If the rate limit is exceeded, the API will respond with the status code HTTP 429 Too Many Requests. Please refer to the section Error codes.

Zodia's API authentication requires each request to be signed.
These requests must be signed using company_pri_key, the private key of your company.
All REST requests must contain the following headers:

1. company-identifier is the identifier provided to you during the setup of your company on the Zodia Platform.
2. request-identifier is an unique randomly generated identifier
3. request-timestamp is the timestamp (milliseconds elapsed since the unix epoch) of when the request is submitted. Please note that the request should be submitted within 5 minutes
4. signature is the message signature(using the SHA256withRSA algorithm). Please refer to the section Signing requests.

All request bodies should have content type application/json and be valid JSON.

Before submitting a payload contained in a POST request, you will need to sign with api_user_pri_key, your private key as an API user.
The content that must be signed is the stringified value of a part of this payload.
For more details about a stringified value, see json-stable-stringify

The signed payload must not include optional and empty fields

The content that must be signed is the stringified value of the object named request.

Example: assuming you want to submit the command to create new outgoing transaction with bitcoins, you will have to submit the payload:

{
    "request": {
        "author": {
            "id": "2336cf5b-a9d2-45e8-b384-5b45d0eb4f03",
            "domainId": "cef1a96b-aa13-443a-b4cc-e3286f2af910"
        },
        "expiryAt": "2022-01-05T10:54:48Z",
        "targetDomainId": "cef1a96b-aa13-443a-b4cc-e3286f2af910",
        "id": "4ffea8f1-aa6d-40b3-9581-070eca1d3529",
        "payload": {
            "accountId": "ea34669c-226d-430c-8633-a3809414536c",
            "parameters": {
                "outputs": [
                    {
                        "destination": {
                            "type": "Address",
                            "address": "2N3oum61eFbwBvA8roU7YuR8UXnmMxr1tCE"
                        },
                        "amount": "5000"
                    }
                ],
                "feeStrategy": {
                    "priority": "High",
                    "type": "Priority"
                },
                "maximumFee": "10000",
                "type": "Bitcoin"
            },
            "id": "91e8cfd2-8ba8-483f-8034-fde52fb82fe7",
            "description": "Create an intent for tx out",
            "customProperties": {},
            "type": "v0_CreateTransactionOrder"
        },
        "description": "Create an intent for tx out",
        "customProperties": {},
        "type": "Propose"
    },
    "signature": "{{signature}}"
}

where {{signature}} is the value obtained by signing the stringified value of the object request. Below is an example of how to sign:

import os, base64, json
from cryptography.hazmat.backends import default_backend
from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import ec

def stringify_transaction_details():
    transaction_details = {
        "author": {
            "id": "2336cf5b-a9d2-45e8-b384-5b45d0eb4f03",
            "domainId": "cef1a96b-aa13-443a-b4cc-e3286f2af910"
        },
        "expiryAt": "2022-01-05T10:54:48Z",
        "targetDomainId": "cef1a96b-aa13-443a-b4cc-e3286f2af910",
        "id": "4ffea8f1-aa6d-40b3-9581-070eca1d3529",
        "payload": {
            "accountId": "ea34669c-226d-430c-8633-a3809414536c",
            "parameters": {
                "outputs": [
                    {
                        "destination": {
                            "type": "Address",
                            "address": "2N3oum61eFbwBvA8roU7YuR8UXnmMxr1tCE"
                        },
                        "amount": "5000"
                    }
                ],
                "feeStrategy": {
                    "priority": "High",
                    "type": "Priority"
                },
                "maximumFee": "10000",
                "type": "Bitcoin"
            },
            "id": "91e8cfd2-8ba8-483f-8034-fde52fb82fe7",
            "description": "Create an intent for tx out",
            "customProperties": {},
            "type": "v0_CreateTransactionOrder"
        },
        "description": "Create an intent for tx out",
        "customProperties": {},
        "type": "Propose"
    }

    return json.dumps(transaction_details, sort_keys=True, separators=(',', ':'))

def sign_transaction_details(details, user):
    with open(os.path.join("keys", user + ".private.pem"), "rb") as private_key_in:
        ec_private_key = serialization.load_pem_private_key(private_key_in.read(),
                                                            password=None,
                                                            backend=default_backend())
        signed_payload = ec_private_key.sign(str.encode(details), ec.ECDSA(hashes.SHA256()))
    b64_signed_payload = base64.b64encode(signed_payload).decode('UTF-8')
    return b64_signed_payload

def create_transaction_payload(details, signature):
    payload = {
            "request": json.loads(details),
            "signature": signature
        }
    }
    return json.dumps(payload, sort_keys=True, separators=(',', ':'))

if __name__ == "__main__":
    stringified_details = stringify_transaction_details()
    user_signature = sign_transaction_details(stringified_details, "[email protected]")
    transaction_payload = create_transaction_payload(stringified_details, user_signature)

    print(transaction_payload) # {"request":{"author":{"id":"2336cf5b-a9d2-45e8-b384-5b45d0eb4f03","domainId":"cef1a96b-aa13-443a-b4cc-e3286f2af910"},"expiryAt":"2022-01-05T10:54:48Z","targetDomainId":"cef1a96b-aa13-443a-b4cc-e3286f2af910","id":"4ffea8f1-aa6d-40b3-9581-070eca1d3529","payload":{"accountId":"ea34669c-226d-430c-8633-a3809414536c","parameters":{"outputs":[{"destination":{"type":"Address","address":"2N3oum61eFbwBvA8roU7YuR8UXnmMxr1tCE"},"amount":"5000"}],"feeStrategy":{"priority":"High","type":"Priority"},"maximumFee":"10000","type":"Bitcoin"},"id":"91e8cfd2-8ba8-483f-8034-fde52fb82fe7","description":"Create an intent for tx out","customProperties":{},"type":"v0_CreateTransactionOrder"},"description":"Create an intent for tx out","customProperties":{},"type":"Propose"},"signature":"MEQCIHuLPOFmbnjWnJ0l6QpYRLMh/6LTwIV6LNlGXRiChProAiBjDQCsvbsGxb6pw9Il/m8zIFmZ+Wh3QFwBmIZJCOk8kA=="}

You will obtain the payload below (prettified for the documentation) that you can submit to Zodia, once you have signed the whole request:

{
    "request": {
        "author": {
            "id": "2336cf5b-a9d2-45e8-b384-5b45d0eb4f03",
            "domainId": "cef1a96b-aa13-443a-b4cc-e3286f2af910"
        },
        "expiryAt": "2022-01-05T10:54:48Z",
        "targetDomainId": "cef1a96b-aa13-443a-b4cc-e3286f2af910",
        "id": "4ffea8f1-aa6d-40b3-9581-070eca1d3529",
        "payload": {
            "accountId": "ea34669c-226d-430c-8633-a3809414536c",
            "parameters": {
                "outputs": [
                    {
                        "destination": {
                            "type": "Address",
                            "address": "2N3oum61eFbwBvA8roU7YuR8UXnmMxr1tCE"
                        },
                        "amount": "5000"
                    }
                ],
                "feeStrategy": {
                    "priority": "High",
                    "type": "Priority"
                },
                "maximumFee": "10000",
                "type": "Bitcoin"
            },
            "id": "91e8cfd2-8ba8-483f-8034-fde52fb82fe7",
            "description": "Create an intent for tx out",
            "customProperties": {},
            "type": "v0_CreateTransactionOrder"
        },
        "description": "Create an intent for tx out",
        "customProperties": {},
        "type": "Propose"
    },
    "signature": "MEQCIHuLPOFmbnjWnJ0l6QpYRLMh/6LTwIV6LNlGXRiChProAiBjDQCsvbsGxb6pw9Il/m8zIFmZ+Wh3QFwBmIZJCOk8kA=="
}

Once the payload (for POST requests) is signed, you will need to sign the request that you send to Zodia.
Using : as separator, please concatenate the values of:

• company-identifier
• request-identifier
• request-timestamp
• decoded value of the url invoked (including query parameters). Example:
  • https://dummy.server/api/core/wallets/{walletId}/transactions/out
  • https://dummy.server/api/core/wallets/{walletId}/transactions/out?limit=25&from=2021-03-29
• payload (for POST requests)

As an example for a GET request, the resulting string will be:
ZTEST:c730a02f-105d-4899-87aa-b1b8280e4a7e:1620141458133:https://dummy.server/api/core/wallets/ZTEST-NOBENF-8P8XKKAO/transactions/out?limit=25&from=2021-03-29:

The content of the header signature is generated by signing the string above with company_pri_key.
Example of code showing how to sign the request:

import os, base64, time, uuid, requests
from cryptography.hazmat.backends import default_backend
from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import padding

def sign(data_to_sign, private_key):
    data_bytes = str.encode(data_to_sign)
    signature = private_key.sign(data_bytes, padding.PKCS1v15(), hashes.SHA256())
    return base64.b64encode(signature).decode('UTF-8')

def sign_for_zodia(company_identifier, url, payload):
    request_identifier = str(uuid.uuid4())
    request_timestamp = str(int(time.time() * 1000))
    data_to_sign = ":".join([company_identifier, request_identifier, request_timestamp, url, payload])
    print(data_to_sign)   # ZTEST:c730a02f-105d-4899-87aa-b1b8280e4a7e:1620141458133:https://dummy.server/api/core/wallets/ZTEST-NOBENF-8P8XKKAO/transactions/out?limit=25&from=2021-03-29:

    with open(os.path.join("keys", company_identifier + ".private.pem"), "rb") as private_key_in:
        rsa_private_key = serialization.load_pem_private_key(private_key_in.read(),
                                                             password=None,
                                                             backend=default_backend())

        signature = sign(data_to_sign, rsa_private_key)
    return company_identifier, request_identifier, request_timestamp, signature

if __name__ == "__main__":
    full_url = "https://dummy.server/api/core/wallets/ZTEST-NOBENF-8P8XKKAO/transactions/out?limit=25&from=2021-03-29"
    headers = sign_for_zodia("ZTEST", full_url, "")

    response = requests.get(full_url, headers={
        "company-identifier": headers[0],         # ZTEST
        "request-identifier": headers[1],         # c730a02f-105d-4899-87aa-b1b8280e4a7e
        "request-timestamp": headers[2],          # 1620141458133
        "signature": headers[3]                   # aZBZNDeDJomgRBZFhV24MbdlyfSiqJuCMgz5mSl+dpxtDDgbadTuin0z920eBD2YFP5g3ccakguQUXPMuLp4Umyet3hGYXb2GiMkKSIA8XocdF8uG2xReSZq+JSbuDSO7yQcxXVK10A6mL2f/zJuTFBRl20jegiHOBcbDlAOUkWS3Vam3KRLA/Nd8ZwOhK6XZbtZWGz0AW9obE7cpEwqUEposucx7J462XAaM9Duh+CF1ALhuo67G0hLYAtwqryRVhUdBvVrqoWgGu3quxfIYgG/8okYv2hHjzBtIfo2VREi4TlgsRXvGPQpSI534S8o9laa5Ddq1f6N2u1sXkE97g==
    })

With V2 endpoints there is a change to the flow for creating and approving a wallet and outgoing transaction.
You will need to retrieve the payload from Zodia after initiating creation to sign and submit it.

Creating/approving wallets and outgoing transfers in V2 use the following flows:

Creating an Outgoing Transaction

1. Create transfer at Zodia
2. Get transfer payload from Zodia
3. Sign and submit transfer payload back to Zodia

Approving an Outgoing Transaction

1. Get transfer approval payload from Zodia
2. Sign and submit transfer approval payload back to Zodia

Creating a Wallet

1. Create wallet at Zodia
2. Get wallet payload from Zodia
3. Sign and submit wallet payload back to Zodia

Approving a Wallet

1. Get wallet approval payload from Zodia
2. Sign and submit wallet approval payload back to Zodia

Zodia's API offers a number of error codes to facilitate your usage and troubleshooting.
Zodia uses HTTP response codes to indicate the success or failure of an API request. In general:

• 200 indicate success
• 4xx range indicate a failure given the information provided(e.g. a required parameter was omitted, etc...)
• 500 indicate an error with Zodia's servers

In addition to these HTTP response codes, Zodia provides in the response payload:

• an error code starting with ER- that should be shared with Zodia for troubleshooting
• a human-readable message providing more details about the errors

The table below describes some errors you may encounter:

The units used in the API are the smallest denomination for a currency per the reference table below:

The API will return status codes for some calls relating to wallets and transactions. These status codes can be mapped to human-readable messages using the following reference tables: