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

Contact: customerservice@zodia.io

• Added API for retrieving the current ledger fees with minimum & maximum values
• 'usdValue' field on wallet balances is deprecated , replaced by 'fiatValue' and 'fiatCurrency'
• Replace walletOwnerId by walletOwner object in /v3/api/custody/wallets
• Change amountLedger type to String in the example in /v3/api/custody/transactions
• Add VASP Country in /v3/api/netwmgmt/vasps

• 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

Your company must be onboarded before you can invoking the APIs.
To complete this setup, generate a key pair for your company. We will refer to these keys as:

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

These keys must be RSA keys (encoded in base 64) with a minimum size of 2048 bits.
Once generated, share the public key company_pub_key with 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)

Share these 2 pieces of information with customerservice@zodia.io

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

• api user email: api-maker@zodia.io
• 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]"

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.

Some API calls require an additional signing process with the maker/authoriser private key, typically when the maker confirms/authoriser approves an instruction (see section "4. Confirm instruction as maker" below). Before submitting the instruction to the HSM, you will need to sign the request payload with api_user_pri_key (API user private key).
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 to sign is the stringified value of the object named request and the resulting signature string should substitute placeholder $$REPLACE.

Assume the request payload is

{
  "request": {
    "key1": "value1",
    "key2": "value2",
    "key3": "value3"
  },
  "signature": "$$REPLACE$$"
}

Below is an example of how to sign it in Python:

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 = {
    "key1": "value1",
    "key2": "value2",
    "key3": "value3"
  }

    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)
    

You will obtain the payload below (prettified for the documentation) to be submitted to the API:

{
      "request": {
        "key1": "value1",
        "key2": "value2",
        "key3": "value3"
      },
      "signature": "MEQCIHuLPOFmbnjWnJ0l6QpYRLMh/6LTwIV6LNlGXRiChProAiBjDQCsvbsGxb6pw9Il/m8zIFmZ+Wh3QFwBmIZJCOk8kA=="
    }

We mandate that all requests are signed. Concatenate the following values using : as a separator:

• company-identifier
• request-identifier
• request-timestamp
• decoded value of the url invoked, for example: https://dummy.server/v3/api/servicedesk/create
• payload (for POST requests only)

Note GET requests will end with a :, for example

ZTEST:c730a02f-105d-4899-87aa-b1b8280e4a7e:1620141458133:https://dummy.server/v3/api/servicedesk/create:

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/v3/api/servicedesk/create:{}

    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/v3/api/servicedesk/create"
    payload = json.dumps({})
    headers = sign_for_zodia("ZTEST", full_url, "{}")

    response = requests.post(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==
    }, data = payload)

This section describes an end-to-end flow to create a wallet, whitelist a beneficiary, whitelist an address for a beneficiary and instruct a transfer.

The APIs aim to be self service, you can check the list of available products and services to fetch the request payload templates based on your account's permissions.

Here is an example :

Request

curl --request POST 'https://hostname.zodia.io/v3/api/servicedesk/products'
--header 'submitter-id: [email protected]' \
--header 'Content-Type: application/json' \
--data-raw 
'{
  "products": [
  ],
  "productIds": [
    "0x0013"
  ],
  "serviceIds": [
    "0x0013-001"
  ],
  "serviceNames": [
  ],
  "requestTypes": [
  ]
}'

Response

HTTP 200

{
  "items": [
    {
      "product": "CUSTODY",
      "productId": "0x0013",
      "serviceId": "0x0013-001",
      "serviceName": "Custody Wallet Management",
      "requestType": "CREATE",
      "description": "Custody Wallet",
      "template": {
        "name": "Wallet_Name",
        "currency": "ETH | BTC",
        "walletOwnerId": "Wallet_Beneficiary_ID"
      }
    }
  ]
}

The template object you see on the response above is what will be requested for any service request creation.

The sample APIs calls below omit authentication information for simplicity, see more about Signing requests.

1. Instruction to create a wallet

Create an Ethereum wallet with name FUND123

Request

curl --request POST 'https://hostname.zodia.io/v3/api/servicedesk/create'
--header 'submitter-id: [email protected]' \
--header 'Content-Type: application/json' \
--data-raw 
'{
    "serviceId": "0x0013-001",
    "payload": {
        "name": "FUND123",
        "currency": "ETH"
    }
}'

Response

HTTP 200

{
  "requestId": "SERV-REQ-0RV7UQ2D56",
  "pluginDetail": {
    "entityId": "ZODCS-NOBENF-E3WB8MB4EI",
    "details": [
      {
        "name": "FUND123",
        "currency": "ETH",
        "isDeFi": false
      }
    ]
  }
}

2. Submit service request

Use the request ID obtained in the previous request to submit the instruction.

Request

curl --request POST 'https://hostname.zodia.io/v3/api/servicedesk/submit' \
--header 'submitter-id: [email protected]' \
--header 'Content-Type: application/json' \
--data '{
  "requestId": "SERV-REQ-0RV7UQ2D56"
}'

Response

HTTP 200

3. Retrieve instruction to sign as maker

Retrieve the HSM instruction to be signed by the maker

Request

curl --request POST 'https://hostname.zodia.io/v3/api/servicedesk/pending' \
--header 'submitter-id: [email protected]' \
--header 'Content-Type: application/json' \
--data '{
  "requestId": "SERV-REQ-0RV7UQ2D56",
}'

Response

HTTP 200

{
  "request": {
    ...
  },
  "signature": "$$REPLACE$$"
}

4. Confirm instruction as maker

Sign the 'request' element with the maker private key and insert the resulting string in 'signature'. The signed instruction is submitted directly to the HSM.

Request

curl --location 'https://hostname.zodia.io/v3/api/servicedesk/approve' \
--header 'submitter-id: [email protected]' \
--header 'Content-Type: application/json' \
--data '{
  "requestId": "SERV-REQ-0RV7UQ2D56",
  "request": {
    ...
  },
  "signature": "MEUCIQDqOsThmTIPlSyqPt2bWYC5FsahAxby/wUjOfdOpnATBgIgdszq9Gnbx8SyTYUcSjTW2OPmnB1a7PPxFO1ReKMWFo0="
}'

Response

HTTP 200

5. Retrieve instruction to sign as authoriser

Request

curl --location 'https://hostname.zodia.io/v3/api/servicedesk/pending' \
--header 'submitter-id: [email protected]' \
--header 'Content-Type: application/json' \
--data '{
  "requestId": "SERV-REQ-0RV7UQ2D56"
}'

Response

{
  "request": {
    ...,
    "type": "Approve|Reject"
  },
  "signature": "$$REPLACE$$"
}

6. Approve instruction as authoriser

To approve an instruction set type to Approve. To reject an instruction, set type to Reject and set a rejectReason.

Request

curl --location 'https://hostname.zodia.io/v3/api/servicedesk/approve' \
--header 'submitter-id: [email protected]' \
--header 'Content-Type: application/json' \
--data '{
  "requestId": "SERV-REQ-0RV7UQ2D56",
  "request": {
    ...,
    "type": "Approve"
  },
  "signature": "MEUCIQCP9Sqzh0jBj0WW++7oVwQyxpSTPfjhB2G7lNjjvom+LwIgcfU521JS3sUFVRHyUhjQGCgQbkb4P4IP/zzcGOxfUEA="
}'

Response

HTTP 200

1. Create instruction to add a beneficiary

Request

curl --request POST 'https://hostname.zodia.io/v3/api/servicedesk/create'
--header 'submitter-id: [email protected]' \
--header 'Content-Type: application/json' \
--data-raw 
'{
    "serviceId": "0x0007-004",
    "payload": {
        "entityType": "INDIVIDUAL",
        "beneficiaryName": "John Smith",
        "registeredAddress": {
            "line1": "10 Downing Street",
            "city": "London",
            "country": "United Kingdom"
        },
        "operatingAddress": {
            "line1": "10 Downing Street",
            "city": "London",
            "country": "United Kingdom"
        }
    }
}'

Response

HTTP 200

{
    "requestId": "SERV-REQ-Y3S874B6IC",
    "pluginDetail": {
        "entityId": "BNF-T20046-JQAPQMNOYA",
        "details": [
            {
                "entityType": "INDIVIDUAL",
                "legalName": "John Smith",
                "registeredAddress": {
                    "line1": "10 Downing Street",
                    "city": "London",
                    "country": "United Kingdom"
                },
                "operatingAddress": {
                    "line1": "10 Downing Street",
                    "city": "London",
                    "country": "United Kingdom"
                }
            }
        ]
    }
}

2. Submit service request

Use the request id obtained in the previous request to submit the instruction

Request

curl --request POST 'https://hostname.zodia.io/v3/api/servicedesk/submit' \
--header 'submitter-id: [email protected]' \
--header 'Content-Type: application/json' \
--data '{
  "requestId": "SERV-REQ-Y3S874B6IC",
}'

Response

HTTP 200

3. Retrieve instruction to sign as maker

Retrieve the HSM instruction to be signed by the maker

Request

curl --request POST 'https://hostname.zodia.io/v3/api/servicedesk/pending' \
--header 'submitter-id: [email protected]' \
--header 'Content-Type: application/json' \
--data '{
  "requestId": "SERV-REQ-Y3S874B6IC",
}'

Response

HTTP 200

{
    "request": {
        ...
    },
    "signature": "$$REPLACE$$"
}

4. Confirm instruction as maker

Sign the 'request' element with the API maker private key, insert the string in 'signature'. The signed instruction is submitted directly to the HSM.

Request

curl --request POST 'https://hostname.zodia.io/v3/api/servicedesk/approve' \
--header 'submitter-id: [email protected]' \
--header 'Content-Type: application/json' \
--data '{
  "requestId": "SERV-REQ-Y3S874B6IC",
  "request": {
    ...
  },
  "signature": "MEQCIAkTlKFSm8IDOS7o0eklI7aU9MvmS6vQUM6NElw9R3ebAiAPd8TMNh6g3QtzDYEPOFxa1EYCr3o+a5ypHa8/RLrN2w=="
}'

Response

HTTP 200

NOTE: Authoriser approval is not required when whitelisting beneficiaries

1. Create instruction to whitelist an address associated with a beneficiary

Whitelist an ETH address linked with beneficiary John Smith which will be use for deposit and withdrawal

Request

curl --request POST 'https://hostname.zodia.io/v3/api/servicedesk/create' \
--header 'submitter-id: [email protected]' \
--header 'Content-Type: application/json' \
--data '{
    "serviceId": "0x0007-007",
    "payload": {
        "address": "0x8dC847Af872947Ac18d5d63fA646EB65d4D99560",
        "blockchain": "ETH",
        "beneficiaryId": "BNF-T20046-WGG997I15N",
        "notes": "Fund A",
        "hostedAddress": true,
        "vaspId": "06ea2d8f-fa02-48f6-87af-c71ea58452as",
        "addressPurpose": [
            "INCOMING, OUTGOING"
        ]
    }
}'

Response

HTTP 200

{
    "requestId": "SERV-REQ-99WPBB0FAG",
    "pluginDetail": {
        "entityId": "467f0fbf-7cd0-4196-b8be-7a33ac66f4f6",
        "details": [
            {
                "cryptoAddress": "0x8dC847Af872947Ac18d5d63fA646EB65d4D99560",
                "currency": "ETH",
                "managingVasp": "06ea2d8f-fa02-48f6-87af-c71ea58452as",
                "beneficiaryId": "BNF-T20046-WGG997I15N",
                "notes": "Fund A",
                "addressPurpose": "INCOMING, OUTGOING"
            },
            {
                "beneficiaryId": "BNF-T20046-WGG997I15N",
                "entityType": "INDIVIDUAL",
                "legalName": "John Smith",
                "legalEntityName": "John Smith",
                "registeredAddress": {
                    "line1": "10 Downing Street",
                    "city": "London",
                    "country": "United Kingdom"
                },
                "operatingAddress": {
                    "line1": "10 Downing Street",
                    "city": "London",
                    "country": "United Kingdom"
                }
            }
        ]
    }
}

2. Submit service request

Use the request ID obtained in the previous request to submit the instruction.

Request

curl --request POST 'https://hostname.zodia.io/v3/api/servicedesk/submit' \
--header 'submitter-id: [email protected]' \
--header 'Content-Type: application/json' \
--data '{
  "requestId": "SERV-REQ-99WPBB0FAG"
}'

Response

HTTP 200

3. Retrieve instruction to sign as maker

Retrieve the HSM instruction to be signed by the maker

Request

curl --request POST 'https://hostname.zodia.io/v3/api/servicedesk/pending' \
--header 'submitter-id: [email protected]' \
--header 'Content-Type: application/json' \
--data '{
  "requestId": "SERV-REQ-99WPBB0FAG",
}'

Response

HTTP 200

{
    "request": {
        ...
    },
    "signature": "$$REPLACE$$"
}

4. Confirm instruction as maker

Sign the 'request' element with the API maker private key, insert the string in 'signature'. The signed instruction is submitted directly to the HSM.

Request

curl --location 'https://hostname.zodia.io/v3/api/servicedesk/approve' \
--header 'submitter-id: [email protected]' \
--header 'Content-Type: application/json' \
--data '{
  "requestId": "SERV-REQ-99WPBB0FAG",
  "request": {
    ...
  },
  "signature": "MEUCIHlH4Zs4zPrhofU9+KsLVLEEcfw6ENHgk7OHLRXhKVJmAiEA8TfaVVjc0XCdnGa8TrRtdmkVQWA5WwJCDNq0CWH02mY="
}'

Response

HTTP 200

5. Retrieve instruction to sign as authoriser

Request

curl --location 'https://hostname.zodia.io/v3/api/servicedesk/pending' \
--header 'submitter-id: [email protected]' \
--header 'Content-Type: application/json' \
--data '{
  "requestId": "SERV-REQ-99WPBB0FAG"
}'

Response

{
    "request": {
        ...,
      "type": "Approve|Reject"
    },
    "signature": "$$REPLACE$$"
}

6. Approve instruction as authoriser

To approve an instruction set type to Approve. To reject an instruction, set type to Reject and set a rejectReason.

Request

curl --location 'https://hostname.zodia.io/v3/api/servicedesk/approve' \
--header 'submitter-id: [email protected]' \
--header 'Content-Type: application/json' \
--data '{
  "requestId": "SERV-REQ-99WPBB0FAG",
  "request": {
    ...,
    "type": "Approve"
  },
  "signature": "MEYCIQCkuiFDtdtl+cbeMewrGgwRycTNuRHmHVrhzR3MlDqX0AIhALIiT+KoYjxlDKtVpwcvXQbL0MuXE/wAeXl4DIulMp3m"
}'

Response

HTTP 200

1. Create transfer instruction

We assumed the wallet has been funded prior to initiating the transfer.

Request

curl --request POST 'https://hostname.zodia.io/v3/api/servicedesk/create'
--header 'Content-Type: application/json' \
--data-raw 
'{
  "serviceId": "0x0014-007",
  "payload": {
    "sender": {
      "type": "WALLETID",
      "value": "ZODCS-NOBENF-E3WB8MB4EI"
    },
    "destination": {
      "type": "BENEFICIARYADDRESSID",
      "value": "467f0fbf-7cd0-4196-b8be-7a33ac66f4f6"
    },
    "amount": "50000",
    "subtractFee": false
  }
}'

Response

HTTP 200

{
    "requestId": "SERV-REQ-A02R2928OC",
    "pluginDetail": {
        "entityId": "TRO-LUXOR-P01HT6O1UT",
        "details": [
            {
              "sender": {
                "type": "WALLETID",
                "value": "ZODCS-NOBENF-E3WB8MB4EI"
              },
              "destination": {
                "type": "BENEFICIARYADDRESSID",
                "value": "467f0fbf-7cd0-4196-b8be-7a33ac66f4f6"
              },
              "amount": "50000",
              "subtractFee": false
            }
        ]
    }
}

2. Submit service request

Use the request id obtained in the previous request to submit the instruction.

Request

curl --request POST 'https://hostname.zodia.io/v3/api/servicedesk/submit' \
--header 'submitter-id: [email protected]' \
--header 'Content-Type: application/json' \
--data '{
  "requestId": "SERV-REQ-A02R2928OC"
}'

Response

HTTP 200

3. Retrieve instruction to sign as maker

Retrieve the HSM instruction to be signed by the maker

Request

curl --request POST 'https://hostname.zodia.io/v3/api/servicedesk/pending' \
--header 'submitter-id: [email protected]' \
--header 'Content-Type: application/json' \
--data '{
  "requestId": "SERV-REQ-A02R2928OC",
}'

Response

HTTP 200

{
  "request": {
    ...
  },
  "signature": "$$REPLACE$$"
}

4. Confirm transfer instruction as maker

Sign the 'request' element with the API maker private key, insert the string in 'signature'

Request

curl --request POST 'https://hostname.zodia.io/v3/api/servicedesk/approve'
--header 'Content-Type: application/json' \
--data-raw 
{
  "requestId": "SERV-REQ-A02R2928OC",
  "request": {
    ...
  },
  "signature": "MEYCIQDgag6BsAjQoKe7BPObXUsCC09X2gk0yrLYtxp8qg+R9QIhAJOT+fD3MrjmHHOKD1PO9nLcKhnUrQYSx/w022fO1z9p"
}

Response

HTTP 200

5. Retrieve instruction to sign as authoriser

Request

curl --location 'https://hostname.zodia.io/v3/api/servicedesk/pending' \
--header 'submitter-id: [email protected]' \
--header 'Content-Type: application/json' \
--data '{
  "requestId": "SERV-REQ-A02R2928OC"
}'

Response

{
  "requestId": "SERV-REQ-A02R2928OC",
  "request": {
    ...,
    "type": "Approve|Reject"
  },
  "signature": "MEQCIA/KgOFOxWQzeTpyZerRjcxucXBgdWBFzBdcczEqurkOAiAwcTIFg2XLgE5pfvV+decUKLEzejk1zYe/DFVxW55pdg=="
}

6a. Approve transfer instruction as authoriser

To approve an instruction set type to Approve. To reject an instruction, set type to Reject and set a rejectReason.

Request

curl --request POST 'https://hostname.zodia.io/v3/api/servicedesk/approve'
--header 'Content-Type: application/json' \
--data-raw 
{
  "requestId": "SERV-REQ-A02R2928OC",
  "request": {
    ...,
    "type": "Approve"
  },
   "signature": "MEQCID0XsCYDvVpo2eLD88LH4CpygowzUVAQGpkqhjbMZuMNAiB6rypnraKaKwRsarWSKJGYnx31NfrBQGekUj6yc7wfTg=="
}

Response

HTTP 200

6b. Reject transfer instruction as authoriser

To reject any type of instruction, set type to Reject and specify a rejectReason

Request

curl --request POST 'https://hostname.zodia.io/v3/api/servicedesk/approve'
--header 'Content-Type: application/json' \
--data-raw 
{
  "requestId": "SERV-REQ-A02R2928OC",
  "request": {
    ...,
    "type": "Reject",
    "rejectReason": "Unknown request"
  },
   "signature": "MEQCID0XsCYDvVpo2eLD88LH4CpygowzUVAQGpkqhjbMZuMNAiB6rypnraKaKwRsarWSKJGYnx31NfrBQGekUj6yc7wfTg=="
}

Response

HTTP 200

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:

HTTP status code	Error code	Error message	Description
400	ER-101	Missing mandatory field: field_name	A mandatory field is missing in the payload received by Zodia
400	ER-102	Entity with id: entity_id does not exist	You are trying to use an entity (company, wallet, transaction, etc…) that does not exist
400	ER-103	Size of the field: field_name must be between min_value and max_value	Length of the value provided does not match the expected size
400	ER-104	Entity with id: entity_id already exists	You are trying to create an entity (company, wallet, transaction, etc…) which already exists
400	ER-107	Field: field_name must not be blank	Field is missing Value of the field is empty
400	ER-108	Field: field_name does not match the expected pattern: regexp_value	You sent a value that does not match the pattern expected by Zodia
400	ER-111	Value of the field: field_name is not a supported cryptocurrency	The cryptocurrency provided is not currently supported by Zodia
400	ER-112	Field: field_name must not be empty	You sent an empty value/list while Zodia is expecting at least one value
400	ER-113	Entity with id: entity_id is deactivated	You are trying to use a deactivated entity
400	ER-114	Field: field_name does not match with user's company	The value you provided for the field (usually "domainId") does not match your company's identifier
400	ER-115	Field: field_name does not match with resource parameter: path_parameter	The value you provided in the payload does not match the path parameter used in the resource
400	ER-116	Value of the field: field_name must contain only digits	You sent a value that is not a numeric value
400	ER-117	Value of the field: field_name must be equal to value	You must send a value strictly equal to the value expected by Zodia
400	ER-121	Field: field_name must be greater than or equal to value	You must send a value greater than or equal to the value expected by Zodia
400	ER-122	Field: field_name must be less than or equal to value	You must send a value lesser than or equal to the value expected by Zodia
400	ER-124	Only max_value minutes of drift are allowed	Zodia allows 5 minute of drift between the signed timestamp provided and the instant that Zodia receives the query
400	ER-202	Header: header must not be blank	Header is missing Value of the header is empty
400	ER-253	Not enough funds	The transfer instruction cannot be created as there are not sufficient funds to pay for the amount and/or fee
400	ER-501	Transaction creation is rejected	The transfer instruction has been rejected due to sender or recipient details
400	ER-502	Mismatch between transaction's wallet currency and field: field_name	The cryptocurrency you provided for the field is not consistent with the wallet used for the transaction
400	ER-503	Value of the field: field_name is not adapted to this endpoint	You provided a value that is not supported by the endpoint you used. Example: "preburn" while using the endpoint "/api/core/transactions"
400	ER-504	Mismatch between field: field1_name and field: field2_name	The fields "field1" and "field2" must have the same value
400	ER-505	Mismatch between transaction's wallet and field: field_name	The value you provided for the field does not match the wallet used for the transaction
400	ER-506	Mismatch between transaction's company and field: field_name	The value you provided does not match the company used for the transaction
400	ER-512	Eth transaction fee-included not allowed	You can't submit a transaction ETH included fees
400	ER-601	Ledger wallet is not compatible with this operation	You are trying to initiate a contract-related transaction while using a wallet that does not support this operation
400	ER-604	Error retrieving the wallet address	Zodia was not able to retrieve the address associated to this wallet
401	ER-210	Signature verification failed	Zodia was not able to verify the signature you provided. Either because: private key that signed the data does not match with public key shared with Zodia Data signed is wrong Please refer to the section Authentication
401	ER-211	Access to this resource is denied	The entitlements defined by Zodia don’t allow you to access this resource
404		Endpoint doesn't exist
405	ER-204	Available methods : available_methods	You must choose from the available methods for an endpoint. Example: GET,POST
429	ER-208	Rate limit or daily quota exceeded
500	ER-1	Unexpected error: error	Zodia encountered an unexpected error and can not fulfill the request Please contact Zodia with the error's identifier beginning with the keyword "ERR"

The units used in the API are the smallest denomination for a currency i.e. Satoshi, Wei, Litoshi.

Status in API responses can be mapped to human-readable messages using the following reference tables:

Status	Description
DRAFT	Request is created and not yet submitted
SUBMITTED	Request is submitted and maker has 120 seconds to confirm
PENDING CONFIRMATION	Request is awaiting maker confirmation
PENDING AUTHORISATION	Request is awaiting approvals
CONFIRMED	Request is completed
CONFIRMATION TIMEOUT	Request was not confirmed by the maker within 120 seconds
APPROVAL TIMEOUT	Request was not approved within the allocated time and expired
REJECTED BY AUTHORISER	Request was rejected by authoriser
REJECTED BY SYSTEM	Request was rejected by system

Status	Description
ACTIVE	Wallet is active, funds are available to spend
DEACTIVATED	Wallet is deactivated, funds are frozen

Status	Description
INITIATED	Transfer is waiting to be posted on chain
POSTED ON CHAIN	Transfer is posted on-chain
CONFIRMATION COMPLETED	Transfer is confirmed after x blocks
FAILED	Transfer has failed and has been posted on chain
UNDER INVESTIGATION	Transfer is under investigation by Zodia
PENDING UNLOCK	Incoming transfer detected on-chain and pending system approval
UNLOCKED	Incoming transfer is approved
REJECTED BY SYSTEM	Incoming transfer rejected by system

One stop shop for instructing transfers, create wallets, whitelist beneficiaries and more. The general idea of the Digital Asset Service Desk is to be self-service. Consult the list of available products and services to find out what you are allowed to do and what payloads are required to create service requests.

Retrieve authorised vasps, whitelisted beneficiaries and addresses.

Retrieve information on custody wallets, balances and transfers.