Use Case 4: Providing Custody Service

Overview

This document provides a walkthrough for integrating with the FinP2P API to facilitate Custody services. From the custodian's perspective, this process includes:

Creating a wallet ID (account) and generating a FinID associated with this wallet.
Retrieving account details such as status and public key.
Signing and approving transactions.
Accessing transaction details.

API Integration Flow

The following table will walk you through the step-by-step sell-side integration involved in providing Custody services:

#	API Reference	Description
	Accounts
1	Create account	Receive an owner request to create a wallet id that will be associated with the CID provided Respond with a CID which will be used as a method to access the wallet.
	Signatures
2	Create a signing request	Receive an owner request to sign the payload hash. Respond with the signature of the hash and id of the request.

Example: Create account, create a signing request

The following is an example walkthrough for creating an account and a signing request.

Create an account request

The Custody adapter will receive this message as a result of the request from an owner to create a new account.

curl --request POST \
     --url https://example.com/accounts \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "userFinP2PId": "simulation:101:b9ab438a-ca78-4b86-8584-19f6f888fd91"
}
'

{
    "id": "bedefc1b-3c2f-11ef-9bb8-f60d12cdf03e",
    "publicKey": "034ac8721ec234bff33a73b9820b855f854165dc25acfcbcefe8984200b94f09b7",
    "status": "READY"
}

Process polling request to check on status of the account creation

curl --request GET \
     --url https://example.com/accounts/bedefc1b-3c2f-11ef-9bb8-f60d12cdf03e \
     --header 'accept: application/json'

{
    "id": "e7bc7d89-3c2f-11ef-9bb8-f60d12cdf03e",
    "publicKey": "021554db777e0db85536c20aa71c476c00632c3dff1c931f112f89c46c28194536",
    "status": "READY"
}

Create a signing request

The Custody adapter will receive this message as a result of an owner to create an intent execution.

curl --request POST \
     --url https://example.com/accounts \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
   "asset":{
      "resourceId":"simulation:102:25552a0c-4bc6-4702-ba80-2f589d98b581",
      "type":"finp2p"
   },
   "executionContext":{
      "executionPlanId":"simulation:106:7218a929-62bb-4bf0-a4e4-411b4924731f",
      "instructionSequenceNumber":2
   },
   "expiry":500,
   "nonce":"0bf0068f05ea8eea6d340f386c42bf969322b97732d0b79e0000000000000000",
   "operationId":"simulation:106:7218a929-62bb-4bf0-a4e4-411b4924731f_2",
   "quantity":"1",
   "":{
      "signature":"b6e01c693796a132541e62c399c07f667dcbe4862e4b34c02872d9f94c38b8015f1dc7ed966133f1751aa9d01eb25f9d64eb7b8c2dba4071786ca98812ba9a4c",
      "template":{
         "hash":"3b97a6b4134bd8e7ea4e621775ebaabe780de48758924d54df0d6d9251b96f50",
         "hashGroups":[
            {
               "fields":[
                  {
                     "name":"nonce",
                     "type":"bytes",
                     "value":"0bf0068f05ea8eea6d340f386c42bf969322b97732d0b79e0000000000000000"
                  },
                  {
                     "name":"operation",
                     "type":"string",
                     "value":"loan"
                  },
                  {
                     "name":"pledgeAssetType",
                     "type":"string",
                     "value":"finp2p"
                  },
                  {
                     "name":"pledgeAssetId",
                     "type":"string",
                     "value":"simulation:102:25552a0c-4bc6-4702-ba80-2f589d98b581"
                  },
                  {
                     "name":"pledgeBorrowerAccountType",
                     "type":"string",
                     "value":"finId"
                  },
                  {
                     "name":"pledgeBorrowerAccountId",
                     "type":"string",
                     "value":"039b75d4316fd84fec8833b47c283e02faa1d451065bc95a67f35030010ec50fa7"
                  },
                  {
                     "name":"pledgeLenderAccountType",
                     "type":"string",
                     "value":"finId"
                  },
                  {
                     "name":"pledgeLenderAccountId",
                     "type":"string",
                     "value":"02e33480e71104d6bc24aedf675086cdfcd763ffbfddf8c2a36ec0cc8e1e9cb153"
                  },
                  {
                     "name":"pledgeAmount",
                     "type":"string",
                     "value":"1"
                  },
                  {
                     "name":"moneyAssetType",
                     "type":"string",
                     "value":"fiat"
                  },
                  {
                     "name":"moneyAssetId",
                     "type":"string",
                     "value":"USD"
                  },
                  {
                     "name":"moneyLenderAccountType",
                     "type":"string",
                     "value":"finId"
                  },
                  {
                     "name":"moneyLenderAccountId",
                     "type":"string",
                     "value":"02e33480e71104d6bc24aedf675086cdfcd763ffbfddf8c2a36ec0cc8e1e9cb153"
                  },
                  {
                     "name":"moneyBorrowerAccountType",
                     "type":"string",
                     "value":"finId"
                  },
                  {
                     "name":"moneyBorrowerAccountId",
                     "type":"string",
                     "value":"039b75d4316fd84fec8833b47c283e02faa1d451065bc95a67f35030010ec50fa7"
                  },
                  {
                     "name":"borrowedMoneyAmount",
                     "type":"string",
                     "value":"1000"
                  },
                  {
                     "name":"returnedMoneyAmount",
                     "type":"string",
                     "value":"1000"
                  },
                  {
                     "name":"openTime",
                     "type":"string",
                     "value":"1720438384"
                  },
                  {
                     "name":"closeTime",
                     "type":"string",
                     "value":"1720438384"
                  }
               ],
               "hash":"872ee05516d62a8638bceec5c810de2ff47841fc218f23e7334278ca0acce892"
            }
         ]
      }
   },
   "source":{
      "account":{
         "finId":"039b75d4316fd84fec8833b47c283e02faa1d451065bc95a67f35030010ec50fa7",
         "type":"finId"
      },
      "finId":"039b75d4316fd84fec8833b47c283e02faa1d451065bc95a67f35030010ec50fa7"
   }

{
    "id": "bedefc1b-3c2f-11ef-9bb8-f60d12cdf03e",
    "signature": "034ac8721ec234bff33a73b9820b855f854165dc25acfcbcefe8984200b94f09b7",
    "status": "READY"
}