Skip to main content

Register a Trader

Prerequisites

Following roles are needed to be able to perform steps described on this page:

  • TRADERONBOARDERPROPOSAL_ACCEPTER
  • TRADERONBOARDERPROPOSAL_VIEWER
  • TRADER_ADMINISTRATOR

See Authorization for more details about roles

There are two ways to register a Trader to the Sales Channel. The first one is to onboard an existing Puro.earth Account Holder as a Trader. The second method is to create a Trader without an underlying connection to an Account Holder.

When an Asset Supplier wants to list their assets in a Sales Channel, they are onboarded in the Sales Channel with a Trader Onboarding Proposal. The Trader Onboarding Proposal contains the details of the trader, such as the trader name and business ID. The Sales Channel must process this proposal in order to onboard the trader into their system.

Both parties, seller and buyer, must exist in the Sales Channel Services when a trade is registered from the Sales Channel to Puro.earth. A trader, buyer in this case, is created into the Sales Channel Services by calling the create trader endpoint.

tip

Get your userId and salesChannelId for later use:

Get the sales channel binding of the currently authenticated user
curl -X 'GET' "/user-services/users/me/saleschannel-binding" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $BEARER"

In this example we store them as environment variables:

export USER_ID="SET_USER_ID_HERE"
export SALESCHANNEL_ID="SET_SALESCHANNEL_ID_HERE"

Onboard a Trader from a Trader Onboarding Proposal​

For an existing Puro.earth Account Holder, you can request Puro.earth to onboard a Trader to your Sales Channel.

After Puro.earth has registered a Trader Onboarding Proposal, you can find it with following snippet:

List trader onboarding proposals
curl -X 'GET' "/saleschannel-services/v1/trader-onboarding-proposals" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $BEARER"

Accept proposal using endpoint POST /saleschannel-services/v1/trader-onboarding-proposals/accept
Reject the proposal using endpoint POST /saleschannel-services/v1/trader-onboarding-proposals/reject

Register a new Trader​

info

You need to assign you User with TRADER_ADMINISTRATOR role with following endpoint:
POST /user-services/users/{userId}/saleschannel-binding/{salesChannelId}/roles

The following snippet is for assigning the TRADER_ADMINISTRATOR role for the Sales Channel User:

curl -X 'POST' \
  'https://scs.api.puro.earth/user-services/users/${USER_ID}/saleschannel-binding/${SALESCHANNEL_ID}/roles?role=TRADER_ADMINISTRATOR' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer eyJ0eX...vqL5QA'

Use following endpoint to create a Trader: POST /saleschannel-services/traders

The payload for trader is as follows:

businessId
required
string

The business ID of the trader.

name
required
string

The name of the trader.

required
object

The address of the legal entity which is being registered as a trader.

{
  • "businessId": "FI-12341234",
  • "name": "ACME Corp",
  • "address": {
    }
}

The following snippet is for creating a Trader for the Sales Channel:

Create a trader
curl -X 'POST' "/saleschannel-services/v1/traders" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $BEARER" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{ \
    "businessId": "FI-12341234", \
    "name": "ACME Corp", \
    "address": { \
      "zipCode": "00100", \
      "city": "Helsinki", \
      "countryName": "Finland", \
      "street": "Long Street", \
      "poBox": "PO-12355" \
    } \
  }'

The succesful response contains id of created trader. Save it for further use.

export TRADER_ID="SET_TRADER_ID_HERE"

Trader's assets and Segregated Accounts​

After a Puro Account Holder has been onboarded as a Trader via the Trader Onboarding Proposal the Account Holder can request Puro.earth to onramp assets into the newly created Trader account.

For every registered Trader Puro.earth creates a separate Account Holder and Account in the registry. This Trader ↔ Sales Channel specific Account Holder Account is a Segregated Account. The Segregated Account ensures that the originating Account Holder (often a Supplier) cannot act on the assets themselves. The assets are in practice reserved for the Sales Channel.