Skip to main content

Trading Assets

info

You need a traderId of the Trader which assets are to be traded. See Discover Assets page to fetch the ID of the trader.

Registering a Trade is an asynchronous process yielding a trade task. Status of the trade is observed from this trade task.

Processing time of a Trade

Due to Puro's transaction approval process the settlement of a trade can be deferred and take some time. The approval is requested from the seller if the seller is a Puro.earth Platform Agreement signed Trader. Until the transaction is either approved or rejected the Task stays in PENDING state.

If the seller trader is not linked to a Puro.earth Platform Agreement signed Trader, or if the transaction auto-approval is turned on by the seller, then the trade is completed almost immediately.

It is recommended that the Sales Channel throttle retry calls to the Trade status endpoint.

Register a Trade​

Trades are registered using POST /saleschannel-services/traders/{traderId}/inventory/trade endpoint. Monetary information, seller and buyer ids, as well as start and end ids of bundles to be traded will be given as the request payload.

Due to the underlying registry changes, the asset start has to always be the first certificate of a bundle.

Detailed payload for registering a trade:

buyerId
required
string

The ID of the trader who is buying the assets.

required
Array of objects non-empty

All assets which are involved in this trade

currency
required
string
Enum: "EUR" "USD"

The currency of the monetary value of this trade.

{
  • "buyerId": "string",
  • "assets": [
    ],
  • "currency": "EUR"
}

Register a trade
curl -X 'POST' "/saleschannel-services/v1/traders/{traderId}/inventory/trade" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $BEARER" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{ \
    "buyerId": "clc0c5of30123rsph3yui9cwo", \
    "assets": [ \
      { \
        "start": "6e0edefa8-cbde-4c19-896a-edafb7a8e030_1", \
        "end": "6e0edefa8-cbde-4c19-896a-edafb7a8e030_100", \
        "unitPrice": 0.01 \
      } \
    ], \
    "currency": "EUR" \
  }'

Check the Trade status​

Via the Get status of a trade task endpoint​

A successful response from registering a trade contains the id of the created trading task which can be used to query for the trade status.

Get status of a trade task
curl -X 'GET' "/saleschannel-services/v1/traders/{traderId}/inventory/trade/{taskId}" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $BEARER"

Resending the Register a Trade task request​

As trade registering endpoint is idempotent with the help of the Idempotency-Key. You can request the status of the trade by resending the exact same payload with the same Idempotency-Key used initially to register the trade.

Response​

Both of these endpoints return the trade task status

taskId
required
string

The ID of this task

status
required
string
Enum: "STARTED" "SUCCESS" "FAILED" "PENDING" "REJECTED"

The status of the transaction.

idempotencyKey
string <^[\w-]{1,64}$> ^[\w-]{1,64}$

Idempotency keys are client-generated strings which ensure that requests can be safely retried.

message
string

Human-readable message field describing the state of the task.

object

Details on the created trade, if the trade task completed successfully.

{
  • "taskId": "cl3y5zbkb0062wuxd52u85agi",
  • "status": "PENDING",
  • "idempotencyKey": "cl3y5zbka0036wuxdtoxdl36a",
  • "message": "Task is waiting to be picked up.",
  • "responsePayload": {
    }
}
Asset bundles

The traded start and end range of the Asset IDs cannot overlap between bundles. For example if the seller has two bundles and the trade contains assets from both, then the trade must contain two separate asset ranges.

For example:

Register a trade
curl -X 'POST' "/saleschannel-services/v1/traders/{traderId}/inventory/trade" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $BEARER" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{ \
    "buyerId": "clc0c5of30123rsph3yui9cwo", \
    "assets": [ \
      { \
        "start": "6e0edefa8-cbde-4c19-896a-edafb7a8e030_1", \
        "end": "6e0edefa8-cbde-4c19-896a-edafb7a8e030_50", \
        "unitPrice": 0.01 \
      }, \
      { \
        "start": "6e0edefa8-cbde-4c19-896a-edafb7a8e030_100", \
        "end": "6e0edefa8-cbde-4c19-896a-edafb7a8e030_150", \
        "unitPrice": 0.01 \
      } \
    ], \
    "currency": "EUR" \
  }'