Use Case 1: Integrating Trading Platform for Investors
Overview
The following is a step by step guide, that highlights the association of the key values in each of the messages that are involved in onboarding the investor, the asset, and the creation and execution of the primary sale.
This includes from the investor (buyer) perspective:
- The creation of the owner profile, which creates a Global FinID that is used to identify the investor (buyer in this case). The FinID used in creating the user is going to be used in designating the payments account for the buyer, in combination with the Escrow Organization ID in which the buyer is associated with.
- The deposit request of funds that will be used to pay for the transaction.
- The execution against the already created primary sale.
- The execution against the a secondary intent.
From the issuer (seller) side:
- The creation of the issuer record, which creates a FinID that is used to identify the issuer (seller) in this case. They FinID used in creating the user is going to be used in designating the destination account in which payment will be made into, including the Escrow Organization ID in which the seller is associated with.
- The creation of the primary sale.
- The generation of the receipt (response) to the execution request.
API Integration Flow
The following table will walk you through step-by-step involved in the trading interface integration, which enables the investor to be onboarded, invest in primary sale, and participate in secondary market:
| # | Action | Description | API Reference | |||
|---|---|---|---|---|---|---|
Onboard the Investor | ||||||
| 1 | Create User Account for Investor | Registers the investor on FinP2P network. | https://finp2p-docs.ownera.io/reference/createownerprofile | |||
| 2 | Add Certificates (optional) | Attach certificate(s) to the investor profile, such as KYC/AML certificates. For FinP2P proposed certificate specifications, please refer to [Certificates] (https://github.com/owneraio/finp2p-certificates-spec) reference page. | https://finp2p-docs.ownera.io/reference/createcertificate | |||
| 3 | Attached documents (option) | Add any other documentation that would be required for the accreditation of the investor. | https://finp2p-docs.ownera.io/reference/addcertificatedoc | |||
| 4 | Share the new investor with Organizations | Allow the users to trade with (shared) the given organization(s) that are setup in the FinP2P network, meaning sharing the profile with the given node. You will also need to share the investor also with the given organization in which the investor uses for escrow and payments services. | https://finp2p-docs.ownera.io/reference/shareprofile | |||
Fund the Account | ||||||
| 5 | Create a request to deposit funds to a payment service | This step creates a deposit request which will be sent to the operator of the payments service which is indicated in the instructions of the given message. Please note based on the integration to the payment system, the response to this message could be processed later on asynchronously. | https://finp2p-docs.ownera.io/reference/createdepositrequest | |||
| 6 | Receive back deposit instructions | Once the payments operator processes the request, a response will be received in the response section of the message which will contain the deposit instructions. If the message was handled synchronously, the response section will contain the deposit instructions in which the investor (or the operator) will need to follow to fund the account. | https://finp2p-docs.ownera.io/reference/createdepositrequest [Response Section] | |||
| 7 | Get Operation | If the message is processed asynchronous, use the Get operation message to poll the status and content for the response to the request. | https://finp2p-docs.ownera.io/reference/getoperation | |||
Perform an Investment in a Primary Sale of a Given Asset | ||||||
| 8 | Pull Assets and look for Intents | Get assets that are shared with the Investor organization, and look for open intents to inform the investor of availability to buy distributed assets. Look for intents of type PrimarySale that have a status of Active. | https://finp2p-docs.ownera.io/reference/the-graphql-schema | |||
| 9 | Invest in the given asset | Invest in the given open Primary Sale by executing the intent. If the message was handled synchronously, the response section will contain the receipt which is the proof of ownership on the token(s) received in the trade. Rejection could be due to varying reasons such as investor accreditation failure, lack of funding, timeout on the execution operation, etc. | https://finp2p-docs.ownera.io/reference/issuetoken | |||
| 10 | Perform the polling for the response | In case the investment is processed asynchronously, use the function to poll for the result of the execution request. The response will contain a receipt that will be the proof of delivery of the asset, or a rejection in case the investment trade failed. | https://finp2p-docs.ownera.io/reference/getoperation | |||
| 11 | Poll for receipt of payment (optional) | Uses GraphQL call in order to receive the receipt as confirmation that payment was processed. | https://finp2p-docs.ownera.io/reference/the-graphql-schema | |||
Participate in Secondary Trading for a Given Asset - Sell the Asset | ||||||
| 12 | Create a sell intent | Create a sell intent against the given asset that was invested in, to allow for secondary market trading. You will need to supply an escrow account (either previously created or create a new one) which will receive the payment in a case of execution. The intent can be pre-signed or be manually signed on execution. | https://finp2p-docs.ownera.io/reference/addassetprofileintent | |||
| 13 | Optional (you can disable/enable the intent) and update it. | In the case you want to created an intent but not make it available for trading yet, you use the disable and then in turn the enable intent functionality. | https://finp2p-docs.ownera.io/reference/updateassetprofileintent https://finp2p-docs.ownera.io/reference/enableassetprofileintent https://finp2p-docs.ownera.io/reference/disableassetprofileintent | |||
| 14 | Respond to signing request | Once the intent you posted is executed, it will be signed by the investor that is requesting the execution and then it is sent to the end point that you assigned in the Create Intent for you to sign. You can either provide an immediate signature (synchronously) or acknowledge and process request (asynchronously). For asynchronous, you will receive a request for the status of the request for signing. | https://finp2p-docs.ownera.io/reference/addassetprofileintent Refer to the section titled "manualSigningCallback". | |||
| 15 | Sent back signature for asynchronous operation | If signing is asynchronous, you will need to respond back with the signature. You will need to respond with the "requestId" value that supplied to your end point during the previous step of the manual singing callback. | [https://finp2p-docs.ownera.io/reference/signatureresult] (https://finp2p-docs.ownera.io/reference/signatureresult) | |||
| 16 | Subscribe to receipt events in GraphQL | In case the investment is processed asynchronously, use the function to poll for the result of the execution of the intent using the GraphQL subscription capability. If intent was executed successfully, the receipt is used as a proof of delivery of the asset and will contain the commercials of the trade. Note the status of an executed intent will be "Not Active" (status = "NON_ACTIVE"). | https://finp2p-docs.ownera.io/reference/the-graphql-schema | |||
Participate in Secondary Trading for a Given Asset - Request an execution against an Intent | ||||||
| 17 | Pull Assets and look for Intents | Get assets that are shared with the given organization, and look for open intents to inform the investor of availability to buy assets. Look for intents of type “BuyingIntent” or “SellingIntent”. Look for intents of type “BuyingIntent” or “SellingIntent”. | https://finp2p-docs.ownera.io/reference/the-graphql-schema | |||
| 18 | Execute against the given secondary intent | Send an execution request against the given intent (buy or sell). If the message was handled synchronously, the response section will contain the receipt which is the proof of ownership on the token(s) received in the trade. Rejection could be due to varying reasons such as investor accreditation failure, lack of funding, timeout on the execution operation, etc. | https://finp2p-docs.ownera.io/reference/transfertoken | |||
| 19 | Perform the polling to receive the response | In case the investment is processed asynchronously, use the function to poll for the result of the execution request. The response will contain a receipt that will be the proof of delivery of the asset, or a rejection in case the investment trade failed. | https://finp2p-docs.ownera.io/reference/getoperation | |||
| 20 | Poll for receipt of payment (optional) | Uses GraphQL call in order to receive the receipt as confirmation that payment was processed. | https://finp2p-docs.ownera.io/reference/the-graphql-schema | |||
Request Funds Withdrawal | ||||||
| 21 | Request fund withdrawal | The user has the option to withdraw the funds that are in the given account by putting in a request for withdrawal. This request is routed to the given payment service provider to process. If the response is processed synchronously, the response section will contain the withdrawal details. | https://finp2p-docs.ownera.io/reference/createwithdrawrequest | |||
| 22 | Receive withdrawal request response | If the request is processed asynchronously, use the get operations to receive the response. | https://finp2p-docs.ownera.io/reference/getoperation | |||
Using the Ownera App for Testing
Your integration testing for distributing assets will require you to have a counterparty to simulate Primary Sale issuance and secondary trading using the Ownera App.
- You will receive a node operator type user in which will allow you to act as an issuer and other investors to trade with
- The escrow payment process will be that of the node that is assigned to you, in which you will be able to administer the investor funds, both for your own test user and for the other investor(s) trading with you.
| # | Action | Example | |||||
|---|---|---|---|---|---|---|---|
Setup an Issuer and the Asset | |||||||
| 1 | Login into the Ownera app using the URL you were provided and select "Assets". | ![image] (https://files.readme.io/9fd90e2-1_-_Asset_Menu.jpg) | |||||
| 2 | Create an asset in which you will execute a primary sale for. The app will also define the issuer for this asset. | ![image] (https://files.readme.io/080d7e9-2_-_Create_Asset.jpg) | |||||
| 3 | This step in the app allows for the issuer to attach documentation for the asset. For the purpose of your testing, you can skip this step or attach documentation if you are testing for this. | ![image] (https://files.readme.io/52323db-3_-_Add_KYA_Document.jpg) | |||||
| 4 | This step in the app allows for the issuer to set regulations for investors investing in the asset. You can skip this step if you are not testing for this. | ![image] (https://files.readme.io/0cce24e-4_-_Add_KYA_Document.jpg) | |||||
| 5 | Asset has been created. Close the dialog. | ![image] (https://files.readme.io/45cb71c-5_-_Asset_Created.jpg) | |||||
| 6 | If the asset is created under a different organization than the one assigned to you, you will need to share the asset with your organization to have access to it. Select the “manage asset sharing”, and then select your organization and click confirm. | ![image] (https://files.readme.io/90f587a-6_-_Share_Asset.jpg) | |||||
Test Investment in a Primary Sale | |||||||
| 7 | Select the asset and select the “Create primary sale”. | ![image] (https://files.readme.io/2365989-7_-_Create_Primary_Sale.jpg) | |||||
| 8 | Enter the details for the primary sale of the asset and click confirm. The “Settlement Escrow” is the service in which the issuer is using to receive the payment from the buyer. | ![image] (https://files.readme.io/7171a13-8_-_Enter_Primary_Sale.jpg) | |||||
| 9 | The details will appear for the asset primary sale. | ![image] (https://files.readme.io/58ef0a9-9_-_Primary_Sales_Details.jpg) | |||||
| 10 | The asset primary sale is ready. Run your integration to execute the primary sale investment for this asset. | n/a | |||||
Test a Sale Intent for the Asset | |||||||
| 11 | Run your integration to execute a selling intent for the asset. | n/a | |||||
| 12 | Create an investor in which will execute your intent. Go to the “Owner” tab and click the +” to add a new investor. | ![image] (https://files.readme.io/16cf6ff-12_-_Create_an_Investor.jpg) | |||||
| 13 | You will need to add funds for the investor. Firstly you will need to open a deposit account for the investor. | ![image] (https://files.readme.io/e831e8f-13_-_Deposit_request.jpg) | |||||
| 14 | Select the escrow service that is used, and denomination for the account. | ![image] (https://files.readme.io/318f026-14_-_Add_deposit_request.jpg) | |||||
| 15 | Given you have an escrow payment capability deployed for your node, you can use the option of “add cash” for the investor. | ![image] (https://files.readme.io/6db4110-15_-_Add_cash.jpg) | |||||
| 16 | Add the funds for the given investor account. Click confirm. After this the investor is ready to be used for testing. | ![image] (https://files.readme.io/537d9f6-16_-_Add_funds.jpg) | |||||
| 17 | Open the investor’s dashboard. You will see the selling intent you have added via the API. Execute against the intent by clicking the “buy” button. | ![image] (https://files.readme.io/536c4ca-17_-_Execute_against_the_intent.jpg) | |||||
| 18 | Select the escrow account that was created for the investor and “Confirm Transaction”. | ![image] (https://files.readme.io/e6fed00-18_-_Execute_intent.jpg) | |||||
| 19 | You should see through your integration the execution request for the given intent you created, and the receipts sent confirming the transaction completion and details. | n/a | |||||
Test Creating a Buying Intent and handling its execution. | |||||||
| 20 | Use your integration to create a buy intent on an asset. | n/a | |||||
| 21 | Use the investor dashboard to execute against the buying intent you created. | ![image] (https://files.readme.io/82bac9b-21_-_Execute_against_the_intent.jpg) | |||||
| 22 | You should see through your integration the execution request for the given intent you created, and the receipts sent confirming the transaction completion and details. | n/a | |||||
Test Execution of Buying or Selling Intent | |||||||
| 23 | Use the investor dashboard to post a buying or selling intent. | ![image] (https://files.readme.io/f9cdae5-23_-_Post_an_Intent.jpg) | |||||
| 24 | Run your integration for querying the intent and execute a training against it. | n/a | |||||
| 25 | You should see through your integration the receipts sent confirming the transaction completion and details. | n/a | |||||
Example: Investment in Primary Sale
The following is an example for the onboarding and funding of the user, and the execution of an investment in a given primary sale:
| Parameter | Description | Example |
|---|---|---|
| Buyer Fin ID (publicKey) | The public key used in creating the user profile, which in turn will be used as the finID for the user when transacting. | 035049f22c30b46477c0991c6de41cf6428cee58bc5dcfe56513b7f16a624185b2 |
| Buyer User Resource ID (id) | The finP2P resource ID for the given user created. | bank-us:101:7fd0cf9b-86ff-4958-9737-6abb4cab9d5a |
| Buyer Certificate ID (id) | The ID for the certificate that was added. | ec634170-8c62-4d55-b324-0391eb30fac1 |
| Buyer Escrow Org ID | The escrow organization that will be used to transact the investment | ownera-escrow |
| Asset ID | The ID assigned to the assigned that was created. | bank-us:102:631dd696-302b-4f6e-b91f-79cc7bf84f54 |
| Primary Sale Intent ID | The ID assigned to the primary sale intent that was created. | bank-us:105:3a360d7a-df60-40b2-9574-eccaa1ed1f08 |
| Issuer Fin ID | The issuer FinID, the public key that is assigned to the issuer. | 024c9f4cda13349113e312bfe6e8860a5186ab90b3d0987cfd43bcdc285303d93a |
| Issuer Escrow Org ID | The escrow organization that will be used to transact between the buyer and issuer. | ownera-escrow |
Create user profile:
Create the investor profile that is going to be trading against primary/secondary intents.
curl --location --request POST 'fi-a.api.int1.ownera.io/finapi/profiles/owner' \
--header 'Content-Type: application/json' \
--data-raw '{
"publicKey": "035049f22c30b46477c0991c6de41cf6428cee58bc5dcfe56513b7f16a624185b2",
"signature": "f5dd4f38c23d3ba99e084e6f72f856b7970bcee07f4b3b2595868e399a0534553be0cc795930009b738830e322337941f276e53cd79041bdb39d6fd6fdf9a199"
}'
{
"isCompleted": true,
"response": {
"id": "bank-us:101:7fd0cf9b-86ff-4958-9737-6abb4cab9d5a"
},
"type": "profile"
}
Attach certificate to the given user:
The attached certificate in this case is called "ownerInfo" which is used to assign a name, email, and what type the investor is.
curl --location --request POST 'http://fi-a.api.int1.ownera.io/finapi/profiles/bank-us:101:7fd0cf9b-86ff-4958-9737-6abb4cab9d5a/certificates' \
--header 'Content-Type: application/json' \
--data-raw '{
"type": "ownerInfo",
"issuanceDate": 1668598695,
"expirationDate": 1700134695,
"data": "{\"email\":\"[email protected]\",\"name\":\"Investor1\",\"type\":\"company\"}"
}'
{
"id": "ec634170-8c62-4d55-b324-0391eb30fac1"
}
Upload and attached documents to certificates:
Upload a document to the given certificate, pointing to a location of the file.
curl --location --request POST 'http://fi-a.api.int1.ownera.io/finapi/profiles/bank-us:101:7fd0cf9b-86ff-4958-9737-6abb4cab9d5a/certificates/ec634170-8c62-4d55-b324-0391eb30fac1' \
--form '=@"/kyc.pdf"'
Associate the user with the given escrow service:
Associate (share) the user to a given organization, in this case, to the organization that is going to provide escrow/payments services for the investor.
curl --location --request POST 'http://localhost:62532/profiles/bank-il:101:a0f25042-c27c-4184-ae93-6488e43541a8/share' \
--header 'Content-Type: application/json' \
--data-raw '{
"organizations": [
"ownera-escrow"
]
}'
n/a
Request deposit instructions:
Place a deposit request for funds into the given escrow account. The account is designated by the buyer fin ID and its associated escrow organization ID. The instruction below requests a USD fiat deposit in the amount of $100,000 into "ownera-escrow" organization.
curl --location --request POST 'http://fi-a.api.int1.ownera.io/finapi/payments/deposit' \
--header 'Content-Type: application/json' \
--data-raw '{
"profileId": "bank-us:101:7fd0cf9b-86ff-4958-9737-6abb4cab9d5a",
"account": {
"account": {
"type": "finId",
"finId": "035049f22c30b46477c0991c6de41cf6428cee58bc5dcfe56513b7f16a624185b2",
"orgId": "ownera-escrow"
},
"asset": {
"type": "fiat",
"code": "USD"
}
},
"amount": "1000000"
}'
{
"cid": "9cd41679a9cfb99e856f1351908df952cae259296a6f49660000000063aaf015",
"isCompleted": false,
"type": "deposit"
}
Get status on request:
Run a get operations to pull for the response on the deposit request.
curl --location --request GET 'http://fi-a.api.int1.ownera.io/finapi/operations/status/9cd41679a9cfb99e856f1351908df952cae259296a6f49660000000063aaf015'
{
"isCompleted": true,
"response": {
"depositInstruction": {
"depositInstruction": {
"account": {
"account": {
"finId": "035049f22c30b46477c0991c6de41cf6428cee58bc5dcfe56513b7f16a624185b2",
"orgId": "ownera-escrow",
"type": "finId"
},
"asset": {
"code": "USD",
"type": "fiat"
}
},
"description": "Bank Adress|100 West Park Avenue|Beneficiary Name|Bank ABC, LCC|Bank Name|First International Bank|Account number|1292929292|Account type|Custodial|Routing number|10299393393|Bic Swift Code|FIRBILITXXX|Reference number|1J2JDJDJDFHJ"
},
"operationId": "690c41f1-bfb6-480f-bd92-8470b8183db6"
}
},
"type": "deposit"
}
Query for open primary sales avaiable for investment:
Query for open intents that are of type "Primary Sale". The intent information will provide you with the details required to execute the intent. The example shows a token of type building that has 40 tokens avaiable for investment in valued at 1 USD each. The intent will be executed via the given escrow "ownera-escrow".
query OpenIntentsPrimarySale {
assets {
nodes {
id
name
organizationId
intents(
filter: [{key: "type", operator: EQ, value: "primarySale"}, {key: "status", operator: EQ, value: "ACTIVE"}]
) {
nodes {
id
type
start
end
status
assetTerm {
amount
}
assetInstruction {
account {
asset {
__typename
}
}
}
settlementTerm {
__typename
asset {
__typename
... on FiatAsset {
code
}
... on FinP2PAsset {
resourceId
}
... on Cryptocurrency {
symbol
}
}
unitValue
}
intent {
... on PrimarySale {
issuerId
sellingSettlementInstruction {
type {
__typename
... on EscrowSellingSettlementInstruction {
__typename
whiteListedEscrows
}
}
accounts {
asset {
__typename
}
identifier {
__typename
... on Iban {
code
}
... on CryptoWalletAccount {
address
}
... on FinIdAccount {
finId
orgId
}
}
}
}
}
}
remainingQuantity
}
}
}
}
}
{
"data": {
"assets": {
"nodes": [
{
"id": "bank-us:102:631dd696-302b-4f6e-b91f-79cc7bf84f54",
"name": "Building 1",
"organizationId": "bank-us",
"intents": {
"nodes": [
{
"id": "bank-us:105:3a360d7a-df60-40b2-9574-eccaa1ed1f08",
"type": "primarySale",
"start": 1671112392,
"end": 1671112450,
"status": "ACTIVE",
"assetTerm": {
"amount": "50"
},
"assetInstruction": {
"account": {
"asset": {
"__typename": "FinP2PAsset"
}
}
},
"settlementTerm": {
"__typename": "SettlementTerm",
"asset": {
"__typename": "FiatAsset",
"code": "USD"
},
"unitValue": "1"
},
"intent": {
"issuerId": "bank-us:101:f09fa8ac-2b83-49de-8779-6ff954c5b181",
"sellingSettlementInstruction": {
"type": {
"__typename": "EscrowSellingSettlementInstruction",
"whiteListedEscrows": null
},
"accounts": [
{
"asset": {
"__typename": "FiatAsset"
},
"identifier": {
"__typename": "FinIdAccount",
"finId": "024c9f4cda13349113e312bfe6e8860a5186ab90b3d0987cfd43bcdc285303d93a",
"orgId": "ownera-escrow"
}
}
]
}
},
"remainingQuantity": "40"
}
]
}
},
]
}
}
}
Place a Primary Sale Execution Request:
The token issuance request will send a request to the tokenization platform of the asset to approve execution. The example below is a request is for an investment in 5 tokens where payments is going to be processed by the organization "ownera-escrow" using the fiat funds avaiable for the buyer in source account to issuer destination account. The response indicates that request processing is not completed (isCompleted = False) and is being processed asynchronously.
curl --location --request POST 'fi-a.api.int1.ownera.io/finapi/tokens/issue' \
--header 'Content-Type: application/json' \
--data-raw '{
"nonce": "c62dacc4f500e8427e8ea45aa15ad0f28000c51e0fe2f73f0000000063a8638e",
"signature": "708a74a19138b78963ffedaab2622ec8dd8d0bcff961a3ed4f46a4068b40b94d3ff1c248a39e56be48f0888e26daf44d163a8a44d0659c05ff29790295e1cef1",
"buyer": "bank-us:101:7572e35f-f9c4-42f6-adee-9669656e6806",
"primarySaleId": "bank-us:105:3a360d7a-df60-40b2-9574-eccaa1ed1f08",
"asset": {
"term": {
"asset": {
"type": "finp2p",
"resourceId": "bank-us:102:631dd696-302b-4f6e-b91f-79cc7bf84f54"
},
"amount": "51"
},
"instruction": {
"destinationAccount": {
"account": {
"type": "finId",
"finId": "039e83762efdb9f4efd8acff6afd4c66a214dee8e288a689a2e9aaf409db75c979",
"orgId": "ownera-escrow"
},
"asset": {
"type": "finp2p",
"resourceId": "bank-us:102:631dd696-302b-4f6e-b91f-79cc7bf84f54"
}
}
}
},
"settlement": {
"term": {
"asset": {
"type": "fiat",
"code": "USD"
},
"amount": "5"
},
"instruction": {
"type": "escrow",
"sourceAccount": {
"account": {
"type": "finId",
"finId": "039e83762efdb9f4efd8acff6afd4c66a214dee8e288a689a2e9aaf409db75c979",
"orgId": "ownera-escrow"
},
"asset": {
"type": "fiat",
"code": "USD"
}
},
"destinationAccount": {
"account": {
"type": "finId",
"finId": "024c9f4cda13349113e312bfe6e8860a5186ab90b3d0987cfd43bcdc285303d93a",
"orgId": "ownera-escrow"
},
"asset": {
"type": "fiat",
"code": "USD"
}
},
"expiry": 36000
}
}
}
'
{
"cid": "fd22e2b4b5d5c31e68fcd433055ab8019591482a2424b7750000000063ac0ac0",
"isCompleted": false,
"type": "token"
}
Get status of execution request:
Use the get operation to get the status on your request. The example shows that the operation has been completed, and request was executed.
curl --location --request GET 'http://localhost:62532/operations/status/fd22e2b4b5d5c31e68fcd433055ab8019591482a2424b7750000000063ac0ac0'
{
"cid": "fd22e2b4b5d5c31e68fcd433055ab8019591482a2424b7750000000063ac0ac0",
"isCompleted": true,
"response": {
"receipt": {
"asset": {
"code": "bank-us:102:631dd696-302b-4f6e-b91f-79cc7bf84f54",
"type": "finp2p"
},
"destination": "bank-us:101:7572e35f-f9c4-42f6-adee-9669656e6806",
"details": {
"transactionDetails": {
"inputs": null,
"outputs": null,
"transactionId": ""
},
"type": "asset"
},
"id": "0108d634-67b5-49f8-872d-edf7f1b46fe2",
"quantity": "1",
"timestamp": 1672219358472625136,
"tradeDetails": {
"intentId": "bank-us:105:3a360d7a-df60-40b2-9574-eccaa1ed1f08",
"intentVersion": "",
"settlementRef": "fe791465-8e55-f427-a7e4-a66ac4d441b5"
}
}
},
"type": "token"
}
Example: Execute a Secondary Sales Intent
The following example is a walkthrough on how to send a request to execution against an open secondary sale intent:
| Parameter | Description | Example |
|---|---|---|
| seller | The investor that posted the intent. This is the user resource ID. | bank-us:101:aa1bc055-8677-4d01-a71a-04e6b07901cc |
| buyer | The investor that is executing the intent. This is the user resource ID. | bank-us:101:a4ac8acb-9801-497b-ad2e-86b227647d13 |
| intentId | The ID for the given open intent. | bank-us:105:50333007-b72c-418e-9f88-7bd865431748 |
| asset >> term >> asset >> resourceID | The resource ID for the given asset. In this case the asset type is finp2p asset. | bank-us:102:234b2028-6362-40fe-bb0c-f71668c08639 |
| asset >> term >> amount | The number of units of token specified in the intent. | 10 |
| asset >> instruction >> sourceAccount >> account + orgID | The FInID (public key) for the seller and the organization (node) that manages the asset. This designates from which Fin Account to transfer the asset. | 02acb467116c385e49feeb639c934dde1fcaa50ee12568fcb8856c87c1ac861632 bank-us |
| asset >> instruction >> destinationAccount >> account + orgID | The FInID (public key) for the buyer and its organization (node) that he or she belongs to. This designates to which Fin Account to transfer the asset to. | 030f5576abf4086b581d95a1a11b17ad138df161720e512e1b04904d92b5f974ea bank-us |
| settlement >> term >> asset >> type + code | Designates the term in which the asset is settled in, in this case it is a USD fiat denominated asset. | fiat USD |
| settlement >> instruction >> sourceAccount | The FInID (public key) for the buyer and the organization (node) that manages the asset. This designates from which Fin Account to transfer the funds from. In this case the fund is managed by ownera-escrow organization. | 030f5576abf4086b581d95a1a11b17ad138df161720e512e1b04904d92b5f974ea ownera-escrow |
| settlement >> instruction >> destinationAccount | The FInID (public key) for the seller and the organization (node) that manages the asset. This designates to which Fin Account to transfer the funds to. In this case the fund is managed by ownera-escrow organization. | 02acb467116c385e49feeb639c934dde1fcaa50ee12568fcb8856c87c1ac861632 ownera-escrow |
Place a Secondary Sale Execution Request:
Once the investor executes against the intent, the token transfer request will send a request to the tokenization platform of the asset to approve execution. Once approved, a request to sign the execution will be sent to the intent creating platform using the end point that was specified in the intent creation message.
The example below is initiated by the investor, and will send an execution request. The request 10 units for the price of $2 each, and the instructions include:
curl --location --request PUT 'https://fi-a.api.int1.ownera.io/finapi/tokens/transfer' \
--header 'Content-Type: application/json' \
--data-raw '{
"nonce": "2ade72398d90c0f3eb9392f8b6718d7e7ca715d4e4e7f1430000000063bebc85",
"signature": "3831650a594757796ee072ac25af7eaaf4e8908869c0056bc3ca5a28b80b469801ee7bc60305a855e3dc1c7310f4df9d970a7b104b4ce302cf1866deed562ff8",
"buyer": "bank-us:101:aa1bc055-8677-4d01-a71a-04e6b07901cc",
"seller": "bank-us:101:a4ac8acb-9801-497b-ad2e-86b227647d13",
"intentId": "bank-us:105:50333007-b72c-418e-9f88-7bd865431748",
"asset": {
"term": {
"asset": {
"type": "finp2p",
"resourceId": "bank-us:102:234b2028-6362-40fe-bb0c-f71668c08639"
},
"amount": "10"
},
"instruction": {
"sourceAccount": {
"account": {
"type": "finId",
"finId": "02acb467116c385e49feeb639c934dde1fcaa50ee12568fcb8856c87c1ac861632",
"orgId": "bank-us"
},
"asset": {
"type": "finp2p",
"resourceId": "bank-us:102:234b2028-6362-40fe-bb0c-f71668c08639"
}
},
"destinationAccount": {
"account": {
"type": "finId",
"finId": "030f5576abf4086b581d95a1a11b17ad138df161720e512e1b04904d92b5f974ea",
"orgId": "bank-us"
},
"asset": {
"type": "finp2p",
"resourceId": "bank-us:102:234b2028-6362-40fe-bb0c-f71668c08639"
}
}
}
},
"settlement": {
"term": {
"asset": {
"type": "fiat",
"code": "USD"
},
"amount": "2"
},
"instruction": {
"type": "escrow",
"sourceAccount": {
"account": {
"type": "finId",
"finId": "030f5576abf4086b581d95a1a11b17ad138df161720e512e1b04904d92b5f974ea",
"orgId": "ownera-escrow"
},
"asset": {
"type": "fiat",
"code": "USD"
}
},
"destinationAccount": {
"account": {
"type": "finId",
"finId": "02acb467116c385e49feeb639c934dde1fcaa50ee12568fcb8856c87c1ac861632",
"orgId": "ownera-escrow"
},
"asset": {
"type": "fiat",
"code": "USD"
}
},
"expiry": 36000
}
}
}
'
Process Execution Response:
You will receive a response that either the execution request has been received and being processed (asynchronously), or a result of the execution request (executed or failed).
Example: Post a Buying or Selling Intent
Place a Secondary Sale Execution Request:
The investor can post a secondary intent that can is broadcasted to all shared parties. Once an execution request is placed by another investor (during which it is signed by the investor), the token transfer request will be routed to the tokenization platform of the asset to approve or reject the execution. If and once approved, the execution will be sent to be signed by the creator of the intent.
The example below is posting a secondary selling intent for 10 units of the token valued at $2 a token. The intent is set to be manually signed upon execution of the intent by the set end point.
curl --location --request POST 'http://fi-a.api.int1.ownera.io/finapi/profiles/asset/bank-us:102:234b2028-6362-40fe-bb0c-f71668c08639/intent' \
--header 'Content-Type: application/json' \
--data-raw '{
"assetTerm": {
"asset": {
"type": "finp2p",
"resourceId": "bank-us:102:234b2028-6362-40fe-bb0c-f71668c08639"
},
"amount": "10"
},
"assetInstruction": {
"account": {
"account": {
"type": "finId",
"finId": "02acb467116c385e49feeb639c934dde1fcaa50ee12568fcb8856c87c1ac861632",
"orgId": "bank-us"
},
"asset": {
"type": "finp2p",
"resourceId": "bank-us:102:234b2028-6362-40fe-bb0c-f71668c08639"
}
}
},
"settlementTerm": {
"asset": {
"type": "fiat",
"code": "USD"
},
"unitValue": "2"
},
"intent": {
"type": "sellingIntent",
"settlementInstruction": {
"type": "escrow",
"destinationAccounts": [
{
"account": {
"type": "finId",
"finId": "02acb467116c385e49feeb639c934dde1fcaa50ee12568fcb8856c87c1ac861632",
"orgId": "ownera-escrow"
},
"asset": {
"type": "fiat",
"code": "USD"
}
}
]
},
"signaturePolicy": {
"type": "manualPolicy",
"endpoint": "https://sitename.com",
"secret": ""
},
"seller": "bank-il:101:a4ac8acb-9801-497b-ad2e-86b227647d13"
},
"start": 1673435671,
"end": 1675085328
}
'
{
"id": "bank-us:105:85c1130e-a5b9-4d03-91fa-5814b256495c"
}
You can disable/enable the intent for the given asset using the Intent ID
curl --location --request PUT 'http:/fi-a.api.int1.ownera.io/finapi/profiles/asset/bank-us:102:234b2028-6362-40fe-bb0c-f71668c08639/intent/bank-us:105:74a40b5f-7e91-4b8a-9152-c70e366d1e8b/disable' \
--header 'Content-Type: application/json' \
--data-raw ''
Sign the executed intent request:
The end point which was set when intent was created will be called upon to sign the execution request. The message will include the signature template in which you need to follow in providing the response signature.
The end point response could be asynchronous or synchronous.
curl --location --request POST 'https://endpointhost.come' \
--header 'Content-Type: application/json' \
--data-raw '{
"requestId": "41f50db6-ed81-4c5e-9086-346800a4283a",
"intentId": "bank-us:105:85c1130e-a5b9-4d03-91fa-5814b256495c",
"signer": "fi-a:101:f9c4f795-1016-4929-91f2-85cb6e17b6af",
"hashFunction": "sha3-256",
"signatureTemplate": {
"hashGroups": [
{
"fields": [
{
"name": "nonce",
"type": "bytes",
"value": "7681e08732751a091c329aee6a766b4c585a1edd59fc6a140000000063cfc542"
},
{
"name": "operation",
"type": "string",
"value": "transfer"
},
{
"name": "assetType",
"type": "string",
"value": "finp2p"
},
{
"name": "assetId",
"type": "string",
"value": "fi-a:102:ad33d6c8-eab1-4272-8d29-3507d0140c68"
},
{
"name": "srcAccountType",
"type": "string",
"value": "finId"
},
{
"name": "srcAccount",
"type": "string",
"value": "03b912a25dea3a55475488aa25b173398d6387d1e80a6755b1de6085565f584648"
},
{
"name": "dstAccountType",
"type": "string",
"value": "finId"
},
{
"name": "dstAccount",
"type": "string",
"value": "029e72b9fbcad2d21485342926cc96072b0bf4dfbf3c3a097390f0e50857e59c56"
},
{
"name": "amount",
"type": "string",
"value": "0x1"
}
],
"hash": "a2d675b256b1e0dde95cdc820a5ed0b84506f406d5b0393242f198009c10454f"
},
{
"fields": [
{
"name": "assetType",
"type": "string",
"value": "fiat"
},
{
"name": "assetId",
"type": "string",
"value": "USD"
},
{
"name": "srcAccountType",
"type": "string",
"value": "finId"
},
{
"name": "srcAccount",
"type": "string",
"value": "029e72b9fbcad2d21485342926cc96072b0bf4dfbf3c3a097390f0e50857e59c56"
},
{
"name": "dstAccountType",
"type": "string",
"value": "finId"
},
{
"name": "dstAccount",
"type": "string",
"value": "03b912a25dea3a55475488aa25b173398d6387d1e80a6755b1de6085565f584648"
},
{
"name": "amount",
"type": "string",
"value": "0x1"
}
],
"hash": "332a66e7159fbc4b61b7b9ffa7beb67c6095899f7e3de6f3d3c72722346703b5"
}
],
"hash": "2d76930d6057b68c6f8c7e6a8f94d69925b7425785daaf6210ae26782cbcbbde"
}
}
'
{"type":"acknowledgement"}
{"type":"signature"}{"signature":"MEQCIFmdjsnClpmqkVo65sfdxtYYpSbYtlVevTSUyQSwquxOAiAg0DFMu4XOeVDahQXpp3sIrq/9RoeU6Pn8CXke4sp66Q=="}
Send back signature:
If response is asynchronous, the end point (or the adapter) you are developing will need to call back with the signature results. If valid, a successful response will be sent. The signature result call needs to contain the value of the requestId that was supplied on the previous step manual signing callback message.
curl --location --request POST 'https://host/tokens/signature-result' \
--header 'Content-Type: application/json' \
--data-raw '{
"requestId": "41f50db6-ed81-4c5e-9086-346800a4283a",
"assetId": "fi-a:102:ad33d6c8-eab1-4272-8d29-3507d0140c68",
"intentId": "bank-us:105:85c1130e-a5b9-4d03-91fa-5814b256495c",
"signature":"MEQCIFmdjsnClpmqkVo65sfdxtYYpSbYtlVevTSUyQSwquxOAiAg0DFMu4XOeVDahQXpp3sIrq/9RoeU6Pn8CXke4sp66Q=="
}'
{"nonce":"7681e08732751a091c329aee6a766b4c585a1edd59fc6a140000000063cfc542"}
Updated about 1 month ago