HomeGuidesRecipesAPI Reference
HomeGuidesAPI ReferenceRecipes

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:

  1. 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.
  2. The deposit request of funds that will be used to pay for the transaction.
  3. The execution against the already created primary sale.
  4. The execution against the a secondary intent.

From the issuer (seller) side:

  1. 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.
  2. The creation of the primary sale.
  3. The generation of the receipt (response) to the execution request.
1128

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:

#ActionDescriptionAPI Reference

Onboard the Investor
1Create User Account for InvestorRegisters the investor on FinP2P network.https://finp2p-docs.ownera.io/reference/createownerprofile
2Add 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
3Attached documents (option)Add any other documentation that would be required for the accreditation of the investor.https://finp2p-docs.ownera.io/reference/addcertificatedoc
4Share the new investor with OrganizationsAllow 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
5Create a request to deposit funds to a payment serviceThis 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
6Receive back deposit instructionsOnce 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]
7Get OperationIf 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
8Pull Assets and look for IntentsGet 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
9Invest in the given assetInvest 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
10Perform the polling for the responseIn 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
11Poll 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
12Create a sell intentCreate 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
13Optional (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
14Respond to signing requestOnce 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".
15Sent back signature for asynchronous operationIf 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)
16Subscribe to receipt events in GraphQLIn 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
17Pull Assets and look for IntentsGet 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
18Execute against the given secondary intentSend 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
19Perform the polling to receive the responseIn 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
20Poll 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
21Request fund withdrawalThe 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
22Receive withdrawal request responseIf 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.
#ActionExample

Setup an Issuer and the Asset
1Login into the Ownera app using the URL you were provided and select "Assets".![image] (https://files.readme.io/9fd90e2-1_-_Asset_Menu.jpg)
2Create 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)
3This 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)
4This 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)
5Asset has been created. Close the dialog.![image]
(https://files.readme.io/45cb71c-5_-_Asset_Created.jpg)
6If 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
7Select the asset and select the “Create primary sale”.![image] (https://files.readme.io/2365989-7_-_Create_Primary_Sale.jpg)
8Enter 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)
9The details will appear for the asset primary sale.![image] (https://files.readme.io/58ef0a9-9_-_Primary_Sales_Details.jpg)
10The 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
11Run your integration to execute a selling intent for the asset.n/a
12Create 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)
13You 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)
14Select the escrow service that is used, and denomination for the account.![image] (https://files.readme.io/318f026-14_-_Add_deposit_request.jpg)
15Given 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)
16Add 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)
17Open 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)
18Select the escrow account that was created for the investor and “Confirm Transaction”.![image] (https://files.readme.io/e6fed00-18_-_Execute_intent.jpg)
19You 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.
20Use your integration to create a buy intent on an asset.n/a
21Use the investor dashboard to execute against the buying intent you created.![image] (https://files.readme.io/82bac9b-21_-_Execute_against_the_intent.jpg)
22You 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
23Use the investor dashboard to post a buying or selling intent.![image] (https://files.readme.io/f9cdae5-23_-_Post_an_Intent.jpg)
24Run your integration for querying the intent and execute a training against it.n/a
25You 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:

ParameterDescriptionExample
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 IDThe escrow organization that will be used to transact the investmentownera-escrow
Asset IDThe ID assigned to the assigned that was created.bank-us:102:631dd696-302b-4f6e-b91f-79cc7bf84f54
Primary Sale Intent IDThe ID assigned to the primary sale intent that was created.bank-us:105:3a360d7a-df60-40b2-9574-eccaa1ed1f08
Issuer Fin IDThe issuer FinID, the public key that is assigned to the issuer.024c9f4cda13349113e312bfe6e8860a5186ab90b3d0987cfd43bcdc285303d93a
Issuer Escrow Org IDThe 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:

ParameterDescriptionExample
sellerThe investor that posted the intent. This is the user resource ID.bank-us:101:aa1bc055-8677-4d01-a71a-04e6b07901cc
buyerThe investor that is executing the intent. This is the user resource ID.bank-us:101:a4ac8acb-9801-497b-ad2e-86b227647d13
intentIdThe ID for the given open intent.bank-us:105:50333007-b72c-418e-9f88-7bd865431748
asset >> term >> asset >> resourceIDThe 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 >> amountThe number of units of token specified in the intent.10
asset >> instruction >> sourceAccount >> account + orgIDThe 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 + orgIDThe 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 + codeDesignates the term in which the asset is settled in, in this case it is a USD fiat denominated asset.fiat

USD
settlement >> instruction >> sourceAccountThe 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 >> destinationAccountThe 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"}