JavaScriptKotlinSwift

Placing Orders

Once the PFI writes a Quote message to the exchange in response to an RFQ, you'd present that Quote to your customer and give them the option to place an Order.

If the customer chooses to place the order, your application will create an Order object, send it to the PFI, listen for status updates, and wait until the order is closed.

Create Order Object

To place an Order in response to a Quote, the first step is to create the Order object. This instantiates a new Order, including metadata such as the customer's DID, the PFI's DID, the exchange ID obtained from the Quote, and the tbDEX protocol version being used.

JavaScript

Kotlin

Swift

Sign Order

Then sign the Order with the customer's Portable DID:

JavaScript

Kotlin

Swift

Send Order

After creating and signing the Order, it needs to be sent to the PFI via the following:

JavaScript

Kotlin

Swift

Listen for Order Status Updates

As the PFI is processing the Order, they'll provide OrderStatus messages. Your application would likely want to show these status updates to your customer to keep them informed of progress.

If you provided a callback URI when sending the RFQ, the PFI will send the OrderStatus messages there.

Otherwise, the PFI will write the OrderStatus messages to the exchange to keep you posted on the Order's status, and your application can poll the exchange to continuously check for OrderStatus messages until a Close message has been written to the exchange:

JavaScript

Kotlin

Swift

Receive Close Message

Once a Close message is written, the exchange is ended and no additional messages can be added to the exchange.

Example of Close message

{
  "metadata": {
    "from": " /* PFI DID */ ",
    "to": " /* CUSTOMER DID */ ",
    "exchangeId": "rfq_01hj2g5wrzfp4tmrfkhz277g9w",
    "protocol": "1.0",
    "kind": "close",
    "id": "close_01hj2g6493fadax5xazq2d2da6",
    "createdAt": "2023-12-20T02:16:59.939Z"
  },
  "data": {
    "reason": "Order fulfilled",
    "success": true
  },
  "signature": " /* PFI's cryptographic signature */ "
}

When the PFI closes the Order, it's important to check the reason on the Close message and report that to your customer, as it could be because the transaction was completed successfully or it could be that the Order has failed.

JavaScript

Kotlin

Swift