3 - Issuance Platform Integration Guide
The Issuers API provides endpoints for issuers to manage authentication, issue activities, and issue holders within the capital markets platform. All endpoints are versioned under {{URL}}/v2/issuers/*
The ERIR Administration platform has the following URLs:
- SANDBOX: https://api.cm-sandbox.onyze.pro/v2/issuers/
- PRODUCTION: https://api.capital-markets.onyze.pro/v2/issuers/
1. Authentication
Most endpoints require authentication via JWT token obtained from the authentication endpoint. The token should be included in the Authorization header as a Bearer token:
Authorization: Bearer <access_token>
To authenticate the issuance platform against the administration platform, the authentication endpoint must be called, sending the Secret and the ClientId of the issuer, as provided by ONYZE.
To make this call, use the endpoint POST {{URL}}/auth/issuers
[LINK to relevant swagger enpoint]
Request Headers:
Authorization: ApiKey 32_CHARACTERS_ISSUER_API_KEY
Request Body:
{ "id": "string (UUID)", "secret": "string (min 32 characters)" }
Response:
If the response is successful, the API will respond with the AccessToken, which will be used to authenticate subsequent calls to the API:
{ "accessToken": "string" }
2. Issue Corporate Activity Request
- The issuance platform communicates via API to ONYZE Capital Markets any operation subject to ERIR approval.
- The ERIR approves and signs the operation, returning the signed information via Webhook to the issuance platform.
- The issuance platform sends the signed information to the issue's Smart Contract.
The issuer's platform can request the ERIR to sign an order, using either the submission of structured EIP-712 data or, if the ERIR has permissions on the smart contract, an EIP-1559 transaction.
This data received by the ONYZE Capital Markets platform must include the information to be signed and additional information so that the ERIR can securely and clearly accept or decline the received operation — thereby avoiding potential fraudulent operations.
Once signed by the ERIR, operations are returned to the issuer's platform via webhook, so it can proceed to send them to the corresponding blockchain.
The types of corporate events associated with the issue that will use this signature request flow are:
- Blocking of funds (total or partial) of a tokenholder
- Blocking of a tokenholder
- Exchange of holdings between tokenholders
- Distribution of returns/yields associated with the issue
- Blocking of the issue
- Address changes of tokenholders (according to the steps defined in the technical requirements document)
- 'Minting' or 'burning' of issue tokens
- Smart contract update
- Change or migration of the issue to another blockchain (included in the required continuity process)
- Change of ERIR for the issue
- Activation, pause, or closure of the issue
Detailed process flow:
-
An order is requested for signature.
-
The issuance platform makes a call to the ONYZE Capital Markets API with the transaction information.
Data to be signed:
{"dataStructured / transaction": "...","info": "string","url_info": "string"} -
Onyze Capital Markets registers the request and it remains pending approval by the ERIR.
-
The ERIR checks pending orders.
-
Does it accept the order?
- No → OY CM rejects the order → notifies the issuance platform via webhook.
- Yes → OY CM updates the order and asks OY Wallet Manager to sign the transaction → the signed TX is sent to the issuance platform via webhook.
To make this call, use the following endpoint:
POST {{URL}}/issuers/{{CLIENT_ISSUER}}/issues/{{CLIENT_ISSUE}}/activities/request
The ClientID and ClientIssueID must be provided, as well as the authentication header with the AccessToken. The body to send in the call can have the following formats:
EIP-712 Typed Data Struct
{
"name": "Issue Test TX 1",
"description": "TX Description",
"infoUrl": "zwww.info.es",
"dataStructured": {
"domain": {
"name": "My amazing dApp",
"version": "1",
"chainId": "1",
"verifyingContract": "0xe2ed0a3C0BD1C914b2d699E8e02d3a3110cD58a1"
},
"types": {
"Bid": [
{
"name": "amount",
"type": "uint256"
},
{
"name": "bidder",
"type": "Identity"
}
],
"Identity": [
{
"name": "userId",
"type": "uint256"
},
{
"name": "wallet",
"type": "address"
}
]
},
"value": {
"amount": "100",
"bidder": {
"userId": "323",
"wallet": "0x3333333333333333333333333333333333333333"
},
"primaryType": "Bid"
}
}
}
Once the activity is approved by the ERIR, a message with the following format will be issued via the issue's webhook in case of approval:
{
"message": "Activity <028a6e2e-77c5-4df5-b6d4-6c118a3b1a51> signed",
"signedTypedData": "0xff668f13b90471e78d5bd240efef0fa12b7e80f0aea222c15d0cc8f79b35d23140368472e149bce8515f9d6239074fd098873cedf44de8862b2853042a10c8731c"
}
In the case of a rejected activity:
{
"message": "Activity <760a17c7-85d6-4e30-81bc-436c67e67cf5> rejected"
}
To check the status of the client Issue Request and whether it has been signed or not, use the following endpoint:
GET {{URL}}/issuers/{{CLIENT_ISSUER}}/issues/{{CLIENT_ISSUE}}/activities/{{REQUEST_ID}}
3. Issue Holder Whitelisting
The issuance platform must notify the ERIR every time a new token holder is registered and added to the smart contract's whitelist.
For this, it is mandatory to send a notification via API to the administration platform.
To make this call, use the following endpoint:
POST {{URL}}/issuers/{{CLIENT_ISSUER}}/issues/{{CLIENT_ISSUE}}/holders
The ClientID and ClientIssueID must be provided, as well as the authentication header with the AccessToken. The body to send in the call will have the following format:
{
"name": "Holder Name",
"address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
}
4. Issue Message Activity Notification
In addition to the above, the ERIR's administration platform will have the ability to receive arbitrary notices from the issuance platform, without the need for these notices to be signed by the ERIR. These notices should be associated primarily with operational, technical, or commercial events relevant to ERIR operators.
To make this call, use the following endpoint:
POST {{URL}}/issuers/{{CLIENT_ISSUER}}/issues/{{CLIENT_ISSUE}}/activities/message
The ClientID and ClientIssueID must be provided, as well as the authentication header with the AccessToken. The body to send in the call will have the following format:
{
"name": "Message Name",
"description": "Message Description",
"infoUrl": "www.info.es"
}