In this example, user authentication and authorization is done outside of the Orangepill platform. Integration on the users level is done using Identities object of Orangepill platform. Use identities to map both your system user and your end users.
System identity
We will need user object and identity object that will represent your system user. System user will provide security context for all API calls to Orangepill platform.
Use Orangepill Dashboard to create new Realm. Realm will provide physical and logical sepration of your data in Orangepill project. Default user and Default identity will be auto-created during that process. Use this identity as system identity.
IMPORTANT: Make sure to have id of your system identity available as a constant inside your project.
API Authentication
Use username and password of system user to authenticate to Orangepill API. Additionally you will need to copy Realm key from Dashboard to build x-api-key authentication token.
Add x-api-key header parameter as authentication token.
Value for x-api-key is: base64encode(username:password:Realm.key)
End user identities
Identities are acting as holders of accounts.
Use Identities to map your users to Orangepill platform. Store username or user_id from your Users table in Identity data object to maintain relation between two identity systems.
If you already have users table with real data, build a batch script to pre-create identities for your existing users.
Map new user
Add code that will create Identity in Orangepill platform upon creation of user in your main system.
Operational model
Make sure you have clear model on movement of digital assets. Each movement of digital assets balance will have a relation to manual administrative or automated operation.
Accounting model
Use Orangepill platform to build accounts necessary to maintain information about movement of all assets included in your exchange operations.
Liquidity accounts
Create ramp accounts for each digital asset in your exchange project. You will use those accounts to maintain liquidity of digital assets.
Use blockchain address of liquidity accounts to maintain liquidity of your exchange. Use this address to deposit digital assets from your liquidity provider.
Populate address field to retrieve blockchain address from ramp account.
To support FIAT operations you must integrate a processes of debit and credit in your FIAT account, to processes of issue and destroy of your virtual FIAT currency.
Cash-in operation
When you receive FIAT amount from your end user, make sure you issue a new supply of virtual FIAT currency. You can map this operation to your other system using data object.
curl --location --request POST'<https://api.orangepill.cloud/v1/currencies/VIRTUAL_FIAT_ACCOUNT/issue> \\--header 'x-api-key: AXVubzpwQDU1dzByYM==' \\--header 'idempotency-key: 27373fabc392933deffdb' \\--header 'Content-Type: application/json' \\--data-raw '{"account": "63a633e84ab7d02420b732ae","amount": "AMOUNT","data": {"description":"Cash in for user X","reference":"REFERENCE_TO_EXTERNAL_OPERATION" }}'
Cash-out operation
When you send FIAT amount to your end user, make sure you destroy a supply of virtual FIAT currency.
curl --location --request POST'<https://api.orangepill.cloud/v1/currencies/VIRTUAL_FIAT_ACCOUNT/destroy> \\--header 'x-api-key: AXVubzpwQDU1dzByYM==' \\--header 'idempotency-key: 27373fabc392933deffdb' \\--header 'Content-Type: application/json' \\--data-raw '{"account": "63a633e84ab7d02420b732ae","amount": "AMOUNT","data": {"description":"Cash out for user X","reference":"REFERENCE_TO_EXTERNAL_OPERATION" }}'
Fees model
To implement fees model, you will need to send fees to your fees accounts before end user executes operation. Make sure you define fees amounts you want to charge your end users for various operations. To implement fee charging you must calculate fee amount and move it to your fees accounts before you execute operation for end user.
Example of charging fees for exchange
user starts exchange operation
calculate fee amount
move fee amount to your fee account
continue executing exchange operation, diminished in amount for the fee amount
To move digital assets to your fee account use transaction operation.
echo 'move 0.0000001 BTC from account to account'curl --location --request POST'<https://api.orangepill.cloud/v1/transactions>' \\--header 'x-api-key: AXVubzpwQDU1dzByYM==' \\--header 'idempotency-key: 27373fabc392933dffabb' \\--header 'Content-Type: application/json' \\--data-raw '{"source": {"account":"634b56217f6a7b0be52dffbd" },"destination": {"account":"6340be52dffbdb56217f6a7b" },"value": 0.0000001,"asset": "BTC","data": {"description":"Payment of 0.0000001 fee in Bitcoin","external_reference":"REFERENCE" }}'
Exchange swap
Implementation of exchange operation must include both movements of digital assets in a swap operation.
FIAT -> Digital Asset
(receive FIAT cash-in)
calculate fee amount
issue FIAT supply
send digital assets from liquidity account to fees virtual account
send digital assets from liquidity account to end user virtual account
Digital Asset → FIAT
calculate fee amount
send digital assets from end user virtual account to fees virtual account
send digital assets from end user virtual account to Liquidity account
destroy FIAT supply
(send FIAT cash-out)
Digital Asset → Digital Asset
calculate fee amount
send digital assets from end user virtual account to fees virtual account
send digital assets from end user virtual account to Liquidity account
send digital assets from Liquidity virtual account to end user virtual account
Front End Integration
Use Orangepill API to show data in your front end application. IMPORTANT: to filter data related to specific user add identity filter in URL of API call. For example: ?holder=IDENTITY
List accounts
To list user accounts and it’s balances for specific user, call accounts endpoint and add identity as a filter.
