Low-Level API JSON

From BlockChainTeleCom wiki
(Redirected from Low Level API JSON)
Jump to: navigation, search

API for BT Participants consists of client-server calls and callbacks on specific events.

Supported formats:

* HTTPS POST JSON to Web API
* HTTPS PUT JSON to Web API
* Direct cUrl call to Blockchain_API
* Recommended json style: "snake_case", lower case only


Contents

Proactive commands

Create a new Service

"object": "create_service"
"params": {"ptservice_id": 196, "memo": {"Name":"Service_196"}, "whitelist_accounts":[25, 30]}

Response:

{"jobid": 123}

Requirements:

object name of the API method
ptservice_id int64 ID of the Service assigned by the Offer Assignee. It should be unique among all services created by the Participant
memo description of the Service as json, with multiple tags. Language for description: English
whitelist [optional] list of int64 Blockchain IDs (via comma) of other participants who can read the Service and create Requests and Orders based on the Service. Example: 10, 25, 36
Each Service can contain multiple Offers (Assets).
Returns jobid identifier to monitor Job Status

Update one of existing Services

"object": "update_service"
"params": {"bcservice_id": 1035, "memo": {"Name":"Service_196"}, "whitelist_accounts":[25, 30]}

Response:

200 OK

Requirements:

object name of the API method
bcservice_id int64 ID of the Service assigned by the blockchain when the Service was created
memo description of the Service as json, with multiple tags. Language for description: English
whitelist [optional] list of int64 Blockchain IDs (via comma) of other participants who can read the Service and create Requests and Orders based on the Service. Example: 10, 25, 36
Returns jobid identifier to monitor Job Status

Create a new Offer (Asset)

"object": "create_asset"
"params": {"ptasset_id": 350, "bcservice_id": 196, "memo": {"Name":"Asset_350"}, "whitelist_accounts":[25, 30]}

Response: {"jobid": 123}

Requirements:

object name of the API method
ptasset_id int64 ID of the Asset assigned by the Offer Assignee. It should be unique among all assets created by the Participant
bcservice_id int64 ID of the Service assigned by the blockchain when the Service was created. Optional. It is recommended to assign each Asset to some Service.
memo description of the Asset as json, with multiple tags. Language for description: English
whitelist [optional] list of int64 Blockchain IDs (via comma) of other participants who can read the Asset and create Requests and Orders based on the Service. Use empty [] array to make asset available to everyone
Returns jobid identifier to monitor Job Status

Update one of existing Offers (Assets)

"object": "update_asset"
"params": {"bcasset_id": 1350, "memo": {"Name":"Asset_350"}, "whitelist_accounts":[25, 30]}

Response: {"jobid": 123}

Requirements:

object name of the API method
bcasset_id int64 ID of the Asset assigned by the blockchain when the Asset was created
memo description of the Asset as json, with multiple tags. Language for description: English
whitelist list of int64 Blockchain IDs (via comma) of other participants who can read the Asset and create Requests and Orders based on the Service. Use empty [] array to make asset available to everyone
Returns jobid identifier to monitor Job Status

Create a new Request for Bids

"object": "create_bid_request"
"params": {"ptbidrequest_id": 650, "bcasset_ids":[850, 930], "memo": {"Name":"Request_650"}, "timeout_sec": 600}

Response: {"jobid": 123}

Requirements:

object name of the API method
ptbidrequest_id int64 ID of the Request for Bids assigned by the Participant. It should be unique among all its requests
bcasset_ids list of int64 IDs of the Assets (via comma) created by other participants
memo description of the Request as json, with multiple tags. Language for description: English
timeout_sec expiration period of the Request, in seconds
Short-term request on one or several assets from one or several service-providers in order to receive bids from them.
Returns jobid identifier to monitor Job Status

Create a new Bid on Request

"object": "create_bid"
"params": {"ptbid_id": 720, "bcrequest_id": 7500, "memo": {"Name":"Bid_720"}, "timeout_sec": 600}

Response: {"jobid": 123}

Requirements:

object name of the API method
ptbid_id int64 ID of the Bid assigned by the Participant. It should be unique among all its bids
bcrequest_id int64 ID of the Request, the Bid is created to
memo description of the Bid as json, with multiple tags. Language for description: English
timeout_sec expiration period of the Bid, in seconds
Short-term Bid on the Request from another service-provider.
Returns jobid identifier to monitor Job Status

Create a new Order on Bid or Asset

"object": "create_order"
"params": {"ptorder_id": 1250, "ptuser_id": 150, "bcasset_id": 850, "bcbid_id": 9850, "amount": 5, "reserved_sum": "12.5", "memo": {"Name":"Order_1250"}, "timeout_sec": 600}

Response: {"jobid": 123}

Requirements:

object name of the API method
ptorder_id int64 ID of the Order assigned by the Participant. It should be unique among all its orders
ptuser_id int64 ID of the user or subscriber assigned by the Participant. This ID allows Participant to mark orders as dedicated to specific customer.
bcbid_id (optional) int64 ID of the Bid, the Order is created on
bcasset_id (optional) int64 ID of the Asset, the Order is created on
amount int64 amount of the Asset
reserved_sum how much SDRt should be reserved for the Order
memo description of the Order as json, with multiple tags. Language for description: English
timeout_sec expiration period of the Order, in seconds
Order on a Bid or an Asset (one of them should be specified) for another service-provider.
After creating new order, the reserved sum is blocked on the Order Issuer account until "Report" transaction, "Cancel" transaction or the Order expiration is happened.
Returns jobid identifier to monitor Job Status

Accept a received Order

"object": "accept_order"
"params": {"bcorder_id": 2450, "memo": {"accept_code":"Order_2450"}}

Response: {"jobid": 123}

Requirements:

object name of the API method
bcorder_id int64 ID of the Order to be accepted
memo description of the Order acceptance as json, with multiple tags. Language for description: English

Offer Issuer calls accept_order to notify Order Issuer that it is ready to serve order. Also it specifies any addition data (activation keys, eSIM profile data, registration data, etc) which are required by purchased service.

Returns jobid identifier to monitor Job Status

Report order: full or part of ordered service is provided

"object": "report_order"
"params": {"bcorder_id": 2450, "amount": 2, "served_sum": "2.5", "memo": {"report_details":"Report Data"}}

Response:

200 OK

Requirements:

object name of the API method
bcorder_id int64 ID of the Order to be served
amount (optional) int64 amount of the provided Asset, 1 by default
served_sum cost of the provided service, in SDRt
memo description of the Report Transaction as json, with multiple tags. Language for description: English
Returns jobid identifier to monitor Job Status


Cancel an own Order

"object": "cancel_order"
"params": {"bcorder_id": 1250}

Response:

200 OK

Requirements:

object name of the API method
bcorder_id int64 ID of the Order to be cancelled. The ID is assigned by the blockchain
Any order could be cancelled by the Order Issuer.
Returns jobid identifier to monitor Job Status

Get my balance

"object": "get_my_balance"
"params": {}

Response:

{"partner_id" : 24, "balance" : "100000.0000"}

Description:

partner_id blockchain id of the account of the current node owner
balance SDRt balance of the account of the current node owner

Request the SDRT balance of the current node owner.

List available accounts

"object": "list_accounts"
"params": {}

Response:

{"jobid": 123}

Get a list of all accounts registered in the blockchain. Accounts are reported through on_list_accounts callback. List includes operator's own account.

---

List available services

"object": "list_services"
"params": {}

Response:

{"jobid": 123}

Get a list of all services registered in the blockchain. Services are reported through on_list_services callback. List includes operator's own services.

---

List available assets

"object": "list_assets"
"params": {}

Response:

{"jobid": 123}

Get a list of all assets registered in the blockchain. Assets are reported through on_list_assets callback. List includes operator's own assets.

---

List bid requests on my assets

"object": "list_bid_requests"
"params": {}

Response:

{"jobid": 123}

Get a list of bid requests of other participants addressed to assets of account owner. Bid requests are reported through on_list_bid_requests callback.

---

List bid requests created by this account

"object": "list_my_bid_requests"
"params": {}

Response:

{"jobid": 123}

Get a list of bid requests of the account owner. Bid requests are reported through on_list_my_bid_requests callback.

---

List active bids on my bid requests

"object": "list_bids"
"params": {}

Response:

{"jobid": 123}

Get a list of bids addressed to the account owner's bid requests. Bids are reported through on_list_bid_requests callback.

---

List bids created by this account

"object": "list_my_bids"
"params": {}

Response:

{"jobid": 123}

Get a list of bids of the account owner. Bids are reported through on_list_my_bids callback.

---

List active orders on my assets or bit requests

"object": "list_orders"
"params": {}

Response:

{"jobid": 123}

Get a list of active orders addressed to the account owner's assets. Orders are reported through on_list_orders callback.

---

List active orders created by my account

"object": "list_my_orders"
"params": {}

Response:

{"jobid": 123}

Get a list of active orders of the account owner. Orders are reported through on_list_my_orders callback.

---

List fill order events (payments) done by/to node account owner

"object": "list_order_filled"
"params": {}

Response:

{"jobid": 123}

Get a list of payments done by node account owner and payments done by other participants to node account owner. Events are reported through on_list_order_filled callback.

---

Events from Blockchain ecosystem

Job status update

"object": "job_status"
"params": {"jobid": 123, "status": "accepted", "bcservice_id|bcasset_id|bcrequest_id|bcbid_id|bcorder_id":345, "details": {"result":{}, error:{}}}

Requirements:

jobid job id returned in the previous API call
status job status. May be "waiting", "published", "accepted", "irreversible" or "failed"
bcservice_id, bcasset_id, bcrequest_id, bcbid_id, bcorder_id id of the blockchain object created with operations create_service, create_asset, create_bid_request, create_bid and create_order/report_order. Reported when status = "accepted"
details optional. Object describing transaction details in blockchain. May contain result and/or error as well as other items

Status explanation: Requirements:

waiting job is placed into execution queue; Newly created job automatically has this status.
published job transaction is created, verified locally, signed with account private key and broadcasted to witnesses for validation.
accepted Transaction was included into the block and applied to the blockchain with single witness confirmation. There is still a small chance that this transaction may be rolled back in the network because of some network connectivity problems.
irreversible 70% or more witnesses have confirmed this transaction, so this transaction is immutable and may not be rolled back
failed a error or network problem occurred resulted in transaction rejection. Details are reported in error object



New Service is created

"object": "service_created"
"params": {"partner_id": 20, "bcservice_id": 2760, "memo": {"Name":"New_Service"}"}

Response:

200 OK

Requirements:

object name of the API event
partner_id int64 Blockchain ID of the Offer Assignee who has created the Service
bcservice_id unique int64 ID of the Service. The ID is used for other proactive commands and events
memo description of the Service as json, with multiple tags. Language for description: English



One of existing Services is updated

"object": "service_updated"
"params": {"partner_id": 20, "bcservice_id": 196, "memo": "{\"Name\":\"Service_Updated\"}"}

Response:

200 OK

Requirements:

object name of the API event
partner_id int64 Blockchain ID of the Offer Assignee who has created the Service
bcservice_id unique int64 ID of the Service. The ID is used for other proactive commands and events
memo description of the Service as json, with multiple tags. Language for description: English




New Offer (Asset) is created

"object": "asset_created"
"params": {"partner_id": 20, "bcservice_id": 2760, "bcasset_id": 850, "memo": "{\"Name\":\"New_Asset\"}"}

Response:

200 OK

Requirements:

object name of the API event
partner_id int64 Blockchain ID of the Offer Assignee who has created the Asset
bcservice_id unique int64 ID of the Service. The ID is used for other proactive commands and events
bcasset_id unique int64 ID of the Asset. The ID is used for other proactive commands and events
memo description of the Asset as json, with multiple tags. Language for description: English




One of existing Offers (Assets) is updated

"object": "asset_updated"
"params": {"partner_id": 20, "bcservice_id": 2760, "bcasset_id": 850, "memo": "{\"Name\":\"New_Asset\"}"}

Response:

200 OK

Requirements:

object name of the API event
partner_id int64 Blockchain ID of the Offer Assignee who has created the Asset
bcservice_id unique int64 ID of the Service. The ID is used for other proactive commands and events
bcasset_id unique int64 ID of the Asset. The ID is used for other proactive commands and events
memo description of the Asset as json, with multiple tags. Language for description: English




New Request on Participant's asset is created

"object": "request_created"
"params": {"partner_id": 20, "bcrequest_id": 7500, "bcasset_id":350, "name": "PRE12345SU", "memo": {"class":"RequestClass"}, "expiration_timestamp": "2020-01-01 07:30:00"}

Response:

200 OK

Requirements:

object name of the API event
partner_id int64 Blockchain ID of the Participant who has created the Request
bcrequest_id unique int64 ID of the Request. The ID is used for other proactive commands and events
bcasset_id int64 blockchain ID of the Participant's Asset
name name of the Request as it is present in the blockchain
memo description of the Request as json, with multiple tags. Language for description: English
expiration_timestamp timestamp (UTC) when the Request is expired
Short-term Request on Participant's asset.



One of third-party Requests is canceled

"object": "request_canceled"
"params": {"bcrequest_id": 7500, "partner_id": 20}

Response:

200 OK

Requirements:

object name of the API event
bcrequest_id unique int64 ID of the Request. The ID is used for other proactive commands and events
partner_id int64 Blockchain ID of the Participant who has created the Request
Any updates on the Request created by another service-provider.




New Bid on Participant's Request is created

"object": "bid_created"
"params": {"partner_id": 20, "bcbid_id": 9850, "bcrequest_id": 650, "name": "PREF12345SUF", "memo": {"class":"class_name"}, "expiration_timestamp": "2020-01-01 07:30:00"}

Response:

200 OK

Requirements:

object name of the API event
partner_id int64 Blockchain ID of the Participant who has created the Bid
bcbid_id unique int64 Blockchain ID of the created Bid. The ID is used for other proactive commands and events
bcrequest_id int64 Blockchain ID of the Request which this bid is addressed to.
name unique name of the Bid as it appears in the Blockchain
memo description of the Bid as json, with multiple tags. Language for description: English
expiration_timestamp timestamp (UTC) when the Bid is expired
Short-term bid on the Participant's Request is created by another service-provider.



One of third-party Bids is canceled

"object": "bid_canceled"
"params": {"partner_id": 20, "bcbid_id": 7500, "bcrequest_id": 650}

Response:

200 OK

Requirements:

object name of the API event
partner_id int64 Blockchain ID of the Participant who has created the Bid
bcbid_id unique int64 Blockchain ID of the Bid.
bcrequest_id int64 Blockchain ID of the Request which this bid was addressed to.




New Order on Participant's Asset / Bid is created

"object": "order_created"
"params": {"partner_id": 20, "bcorder_id": 2450, "bcasset_id": 350, "bcbid_id": 720, "order_sum": 12.5, "order_amount": 5, "memo": {"Name":"New_Order"}, "expiration_timestamp": "2020-01-01 07:30:00+00"}

Response:

200 OK

Requirements:

object name of the API event
partner_id int64 Blockchain ID of the Participant who has created the Order
bcorder_id unique int64 ID of the Order. The ID is used for other proactive commands and events
bcasset_id int64 ID of the Asset assigned by the Participant
bcbid_id int64 ID of the Bid assigned by the Participant, optional, may be null
order_sum cost of the order in SDRt
order_amount number of asset items in the order
memo description of the Order as json, with multiple tags. Language for description: English
expiration_timestamp timestamp with time zone when the Order is expired

One of Paticipant's Orders is updated

"object": "my_order_updated"
"params": {"partner_id": 20, "ptorder_id": 7500, "event": "Order payed", "served_sum": 5.5, "memo": {"Name":"Updated_Order"}}

Response:

200 OK

Requirements:

object name of the API event
partner_id int64 Blockchain ID of the Participant who has updated the Order
ptorder_id int64 ID of the Order assigned by the Participant
event Reason for the Order update: "Order accepted", "Order payed", "Order completed"
served_sum How much SDRt the Order is served with
memo description of the Order update as json, with multiple tags. Language for description: English
Any updates made by another service-provider on the Participant's Order.



One of third-party Orders is cancelled or expired

"object": "order_cancelled"
"params": {"bcorder_id": 2450, "event": "expired", "memo": "{\"Name\":\"Cancelled_Order\"}"}

Response:

200 OK

Requirements:

object name of the API event
bcorder_id unique int64 ID of the Order. The ID is used for other proactive commands and events
event Reason for the Order update: "cancelled", "expired"
memo description of the Order cancellation as json, with multiple tags. Language for description: English
Cancellation of the Order created by another service-provider.


New "order filled" event (payment) was registered in the blockchain

"object": "order_filled"
"params": { "history_id": 1055, "partner_id": 27, "bcorder_id": 1227, "match_partner_id": 30, "match_bcorder_id": 1272, "received_sdr":"15.5500", "bcasset_id":810, "asset_amount":1, "ptorder_id":2007, "ptuser_id": 12, "memo":{"class":"class-name", ...} }

"params": {"jobid": 123, "status":"done" } when finished 


Requirements:

object name of the API event
history_id int64 Blockchain ID of the event registered in the network
partner_id int64 Blockchain ID of the Participant who has created the Order and who receives or sends payment. Must be id of the node owner account.
bcorder_id unique int64 ID of the Order created by node owner as it was registered in the blockchain.
match_partner_id int64 Blockchain ID of the of the Participant who has created matching order.
match_bcorder_id unique int64 ID of the Order created by another participant and which produced bargain between node owner and another participant.
received_sdr amount of SDRt tokens received by node owner in this trade operation. received_sdr may be negative which indicates that SDRt tokens were payed.
bcasset_id int64 ID of the Asset created by node owner or another participant which was used in this trade operation.
asset_amount amount of the Asset which was trade in this operation. Positive value indicates that Asset was bought. Negative value indicates that Asset was sold
ptorder_id int64 ID of the Order assigned by the Participant during Order creation
ptuser_id int64 ID of the user or subscriber assigned by the Participant during Order creation
memo description of the matching Order specified by another participant during Order creation or Reporting order

"Order filled" event occurs when two participants create matching orders, one with Order create operation and another with Report order operation. This triggers trade operation and corresponded amount of SDRt tokens flow from one account to another. Both participants receive this notification.

---

Receive list of available accounts

"object": "on_list_accounts"
"params": {"jobid": 123, "account":{"partner_id": 27, "balance": "12030.25", "name":"super-telecom", "url":"https://wiki.blockchaintele.com", "memo":{"class":"class-name", ...} } }

"params": {"jobid": 123, "status":"done" } when finished 

Requirements:

object name of the API event
jobid id of the list_services job
partner_id int64 Blockchain ID of the Participant
balance SDRt balance of Participant
name unique name of the Participant as it was registered in the Blockchain
url Official URL of the Participant
memo description of the Participant as json, with multiple tags. Language for description: English

---

Receive list of available services

"object": "on_list_services"
"params": {"jobid": 123, "service":{"bcservice_id":777, "partner_id":27, "name":"pref1234suf", "memo":{"class":"class-name", ...} } }

"params": {"jobid": 123, "status":"done" } when finished 

Requirements:

object name of the API event
jobid id of the list_services job
partner_id int64 Blockchain ID of the Offer Assignee who has created the Service
bcservice_id unique int64 ID of the Service. The ID is used for other proactive commands and events
name unique name of the Service as it was registered in the Blockchain
memo description of the Service as json, with multiple tags. Language for description: English

---

Receive list of available assets

"object": "on_list_assets"
"params": {"jobid": 123, "asset":{"partner_id":27, "bcasset_id":810, "bcservice_id":777, "name":"PREF1234SUF", "memo":{"class":"class-name", ...} } }

"params": {"jobid": 123, "status":"done" } when finished 


Requirements:

object name of the API event
jobid id of the list_assets job
partner_id int64 Blockchain ID of the Offer Assignee who has created the Asset
bcasset_id unique int64 ID of the Asset. The ID is used for other proactive commands and events
bcservice_id unique int64 ID of the Service. The ID is used for other proactive commands and events
name unique name of the Asset as it was registered in the Blockchain
memo description of the Asset as json, with multiple tags. Language for description: English

---

Receive list of bid requests on my assets

"object": "on_list_bid_requests"
"params": {"jobid": 123, "bid_request":{"partner_id":27, "bcrequest_id":181, "bcasset_id":810, "toprovider_id":76, "expiration_timestamp":"2019-01-18T10:00:00", "name":"pref1234suf", "memo":{"class":"class-name", ...} } }

"params": {"jobid": 123, "status":"done" } when finished 


Requirements:

object name of the API event
jobid id of the list_bid_requests job
partner_id int64 Blockchain ID of the Participant who has created the Request
bcrequest_id unique int64 ID of the Request. The ID is used for other proactive commands and events
bcasset_id int64 blockchain ID of the Participant's Asset
toprovider_id int64 Blockchain ID of the Participant to whom the Request is addressed to. Must be id of the account of the node owner.
name unique name of the Request as it was registered in the Blockchain
memo description of the Request as json, with multiple tags. Language for description: English
expiration_timestamp timestamp (UTC) when the Request is expired

---

Receive list of bid requests created by this account

"object": "on_list_my_bid_requests"
"params": {"jobid": 123, "bid_request":{"partner_id":27, "bcrequest_id":181, "bcasset_ids":[810,1230,1812] "toprovider_ids":[76,81,108], "expiration_timestamp":"2019-01-18T10:00:00", "name":"pref1234suf", "memo":{"class":"class-name", ...} } }

"params": {"jobid": 123, "status":"done" } when finished 


Requirements:

object name of the API event
jobid id of the list_my_bid_requests job
partner_id int64 Blockchain ID of the Participant who has created the Request
bcrequest_id unique int64 ID of the Request. The ID is used for other proactive commands and events
bcasset_ids list of int64 blockchain IDs of the Assets which this request is addressed to.
toprovider_ids list of int64 Blockchain IDs of the Participants to whom the Request is addressed to.
name unique name of the Request as it was registered in the Blockchain
memo description of the Request as json, with multiple tags. Language for description: English
expiration_timestamp timestamp (UTC) when the Request is expired


---

Receive list of active bids on my bid requests

"object": "on_list_bids"
"params": {"jobid": 123, "bid":{"partner_id":27, "bcbid_id":1218, "bcrequest_id":181, "expiration_timestamp":"2019-01-18T07:00:00", "name":"pref1234suf", "memo":{"class":"class-name", ...} } }

"params": {"jobid": 123, "status":"done" } when finished 


Requirements:

object name of the API event
jobid id of the list_bids job
partner_id int64 Blockchain ID of the Participant who has created the Bid
bcbid_id unique int64 Blockchain ID of the created Bid. The ID is used for other proactive commands and events
bcrequest_id int64 Blockchain ID of the Request which this bid is addressed to.
name unique name of the Bid as it appears in the Blockchain
memo description of the Bid as json, with multiple tags. Language for description: English
expiration_timestamp timestamp (UTC) when the Bid is expired

---

Receive list of bids created by this account

"object": "on_list_my_bids"
"params": {"jobid": 123, "bid":{"partner_id":27, "bcbid_id":1218, "bcrequest_id":181, "expiration_timestamp":"2019-01-18T07:00:00", "name":"pref1234suf", "memo":{"class":"class-name", ...} } }

"params": {"jobid": 123, "status":"done" } when finished 


Requirements:

object name of the API event
jobid id of the list_my_bids job
partner_id int64 Blockchain ID of the Participant who has created the Bid
bcbid_id unique int64 Blockchain ID of the created Bid. The ID is used for other proactive commands and events
bcrequest_id int64 Blockchain ID of the Request which this bid is addressed to.
name unique name of the Bid as it appears in the Blockchain
memo description of the Bid as json, with multiple tags. Language for description: English
expiration_timestamp timestamp (UTC) when the Bid is expired

---

Receive list of active orders on my assets or bit requests

"object": "on_list_orders"
"params": {"jobid": 123, "order":{"partner_id":27, "bcorder_id":1227, "bcasset_id":810, "bcbid_id":1218, "order_reserved_sum":"1132.50", "order_sum":"1510.00", "order_amount":"20", "toprovider_id":76, "ptorder_id":2007, "ptuser_id":12,  "expiration_timestamp":"2019-01-18T12:00:00", "memo":{"class":"class-name", ...},  "accepted_memo":{"class":"class-name", ...} } }

"params": {"jobid": 123, "status":"done" } when finished 


Requirements:

object name of the API event
jobid id of the list_orders job
partner_id int64 Blockchain ID of the Participant who has created the Order
bcorder_id unique int64 ID of the Order. The ID is used for other proactive commands and events
bcasset_id int64 ID of the Asset assigned by the Participant
bcbid_id int64 ID of the Bid assigned by the Participant, optional, may be null
order_reserved_sum not payed part of the order in SDRt, the number of unsold asset items can be calculated as order_reserved_sum * order_amount / order_sum
order_sum total cost of the order in SDRt, the price of single asset item for sale is defined by ratio order_sum/order_amount
order_amount initial number of asset items in the order for sale, the price of single asset item is defined by ratio order_sum/order_amount
toprovider_id int64 Blockchain ID of the Participant which the Order is addressed to. Must be id of the account of the node owner.
ptorder_id int64 ID of the Order assigned by the Participant. It should be unique among all orders of the Participant.
ptuser_id int64 ID of the user or subscriber assigned by the Participant. This ID allows Participant to mark orders as dedicated to specific customer.
memo description of the Order as json, with multiple tags. Language for description: English
accepted_memo Order addressee transfers this information to order creator via accepted_order call.
expiration_timestamp timestamp with time zone when the Order is expired

---

Receive list of active orders created by this account

"object": "on_list_my_orders"


"params": {"jobid": 123, "order":{"partner_id":27, "bcorder_id":1227, "bcasset_id":810, "bcbid_id":1218, "order_reserved_sum":"1132.50", "order_sum":"1510.00", "order_amount":"20", "toprovider_id":76, "ptorder_id":2007, "ptuser_id":12,  "expiration_timestamp":"2019-01-18T12:00:00", "memo":{"class":"class-name", ...},  "accepted_memo":{"class":"class-name", ...} } }

"params": {"jobid": 123, "status":"done" } when finished 


Requirements:

object name of the API event
jobid id of the list_orders job
partner_id int64 Blockchain ID of the Participant who has created the Order. Must be id of the account of the node owner.
bcorder_id unique int64 ID of the Order. The ID is used for other proactive commands and events
bcasset_id int64 ID of the Asset assigned by the Participant
bcbid_id int64 ID of the Bid assigned by the Participant, optional, may be null
order_reserved_sum not payed part of the order in SDRt, the number of unsold asset items can be calculated as order_reserved_sum * order_amount / order_sum
order_sum total cost of the order in SDRt, the price of single asset item for sale is defined by ratio order_sum/order_amount
order_amount initial number of asset items in the order for sale, the price of single asset item is defined by ratio order_sum/order_amount
toprovider_id int64 Blockchain ID of the Participant which the Order is addressed to.
ptorder_id int64 ID of the Order assigned by the Participant. It should be unique among all orders of the Participant.
ptuser_id int64 ID of the user or subscriber assigned by the Participant. This ID allows Participant to mark orders as dedicated to specific customer.
memo description of the Order as json, with multiple tags. Language for description: English
accepted_memo Order addressee transfers this information to order creator via accepted_order call.
expiration_timestamp timestamp with time zone when the Order is expired


---

Receive list of order filled events (payments)

"object": "on_list_order_filled"
"params": {"jobid": 123, "order_filled":{ "history_id": 1055, "partner_id": 27, "bcorder_id": 1227, "match_partner_id": 30, "match_bcorder_id": 1272, "received_sdr":"15.5500", "bcasset_id":810, "asset_amount":1, "ptorder_id":2007, "ptuser_id": 12, "memo":{"class":"class-name", ...} } }

"params": {"jobid": 123, "status":"done" } when finished 


Requirements:

object name of the API event
history_id int64 Blockchain ID of the event registered in the network
partner_id int64 Blockchain ID of the Participant who has created the Order and who receives or sends payment. Must be id of the node owner account.
bcorder_id unique int64 ID of the Order created by node owner as it was registered in the blockchain.
match_partner_id int64 Blockchain ID of the of the Participant who has created matching order.
match_bcorder_id unique int64 ID of the Order created by another participant and which produced bargain between node owner and another participant.
received_sdr amount of SDRt tokens received by node owner in this trade operation. received_sdr may be negative which indicates that SDRt tokens were payed.
bcasset_id int64 ID of the Asset created by node owner or another participant which was used in this trade operation.
asset_amount amount of the Asset which was trade in this operation. Positive value indicates that Asset was bought. Negative value indicates that Asset was sold
ptorder_id int64 ID of the Order assigned by the Participant during Order creation
ptuser_id int64 ID of the user or subscriber assigned by the Participant during Order creation
memo description of the matching Order specified by another participant during Order creation or Reporting order

---

Error report

"object": "error_report"
"params": { "source":"procedure_name", "type:"general_sql", "details":{} }


Requirements:

source name of the procedure where error was detected
type type of error
details any error-specific details

This callback notifies operator about any errors detected in blockchain node operation, blockchain network, and API calls execution.

Billing and Cash Flow

BTBillingDiagram.png

Direct Billing and "Pay-per-Usage" principle provide easy implementation for Participants and fair policy for subscribers. It means that Assignee has guarantee payment for its services, and Issuer pays for consumed services only.

It allows building very flexible packages for subscribers, with combination of mobile services from multiple Operators and of value-added services from multiple Providers. Major cases are described at "Use Cases" section.

Every time a new Request is created, appropriate amount of SDRs is reserved (blocked) on the Issuer's wallet. It provides payment guarantee for the service, so Assignee is able to start servicing the subscriber directly. It's necessary to publish "Report" transaction to notify that the customer was served, otherwise the reserved sum is unblocked after expiration of the validity period and become available for other payments.