Use cases

1) Integrating an exchange on your website

Goal

add an exchange form to the website with currency/network selection, address validation, and order creation.

Endpoints

• v2: POST /api/v2/instruments/public/validate-address, POST /api/v2/instruments/public/one, GET /api/v2/instruments/public, POST /api/v2/orders/public/create, POST /api/v2/orders/public/set-email
• v1 (additionally if statuses/storefront are needed): GET /api/v1/instruments/public, GET /api/v1/instruments/public/one, POST /api/v1/instruments/public/validate-address

Flow

1. Load the catalog of active instruments (currency + network) to build the “Give/Receive” lists.
2. Upon the user’s selection, request details for the “receive” instrument (precision, memo/tag, limits).
3. Validate the destination address via validate-address.
4. Create an order: POST /api/v2/orders/public/create (v2 is recommended). Save the orderId and display the depositAddress to the user.
5. (Optional) add an email to the order: POST /api/v2/orders/public/set-email — for user notifications.
6. Display a screen with payment instructions for the depositAddress and a timer.

2) Fetching and displaying rates

Goal

show the user up-to-date rates for the selected pair.

Endpoints

• v1: GET /api/v1/rates/public/one — public rate in JSON.

Flow

1. When the user selects a pair, request the public rate via rates/public/one.
2. Display the rate, minimum/maximum amounts (if returned), and the freshness timestamp.
3. (Optional) apply visual “markup” to the showcased rate (see Scenario 4), but do not use the adjusted rate to actually create an order in a different API version.

3) Creating and tracking orders

Goal

create an order and provide the user with a clear execution status.

Endpoints

• v2: POST /api/v2/orders/public/create, POST /api/v2/orders/public/set-email
• v1: POST /api/v1/orders/public/create, GET /api/v1/orders/public-info, GET /api/v1/orders/public/latest, POST /api/v1/orders/public/accept-rate-mode-change, POST /api/v1/orders/public/request-refund, GET /api/v1/orders/order-refund-info

Flow (v2 — recommended for creation)

1. Validate input and the destination address.
2. Create an order: v2/orders/public/create → obtain orderId, depositAddress.
3. Offer “Add email”: v2/orders/public/set-email.
4. Show the user deposit instructions.

Status tracking (storefront and user account)

• Storefront “latest exchanges”: GET /api/v1/orders/public/latest.
• Details of a specific order: GET /api/v1/orders/public-info?orderId=...&destinationAddress=... — arrays deposits/withdrawals, confirmations, txId, networkFee.
• Change of rate mode on demand: POST /api/v1/orders/public/accept-rate-mode-change.
• Refunds: POST /api/v1/orders/public/request-refund → details via GET /api/v1/orders/order-refund-info.

4) Checking transaction status

Goal

give the user transparency on the progress of deposits and withdrawals.

Endpoints

• v1: GET /api/v1/orders/public-info, GET /api/v1/orders/order-refund-info

Flow

1. Poll public-info periodically by orderId and destinationAddress.
2. In the deposits[0] block, analyze isPending, confirmations, txId, depositAddress.
3. When the deposit is confirmed — display withdrawal information from the withdrawals array (amount, networkFee, txId).
4. In case of a refund — get details via order-refund-info and show the status “Refund in progress/complete”.