diff --git a/docs/_data/navigation.yml b/docs/_data/navigation.yml index 7d3b59b0..9ea292ae 100644 --- a/docs/_data/navigation.yml +++ b/docs/_data/navigation.yml @@ -59,7 +59,7 @@ docs: - title: '  Telegram' url: /docs/telegram/ - title: '  API' - url: /docs/api-v1/ + url: /docs/api-v0.1/ - title: 'Best Practices' url: /docs/best-practices/ diff --git a/docs/_includes/api-v0.1.html b/docs/_includes/api-v0.1.html new file mode 100644 index 00000000..143fbc8e --- /dev/null +++ b/docs/_includes/api-v0.1.html @@ -0,0 +1,21 @@ + + RobotSats REST API v0.2 + + + + + + + + + + + \ No newline at end of file diff --git a/docs/_pages/docs/03-understand/11-api-v0.1.md b/docs/_pages/docs/03-understand/11-api-v0.1.md new file mode 100644 index 00000000..91bb0e51 --- /dev/null +++ b/docs/_pages/docs/03-understand/11-api-v0.1.md @@ -0,0 +1,11 @@ +--- +layout: default +title: RoboSats API v0.1 +permalink: /docs/api-v0.1/ +sidebar: + title: 'API' + nav: docs +src: "_pages/docs/03-understand/11-api-v0.1.md" +--- + +{% include api-v0.1.html %} \ No newline at end of file diff --git a/docs/_pages/docs/03-understand/11-api.md b/docs/_pages/docs/03-understand/11-api.md deleted file mode 100644 index 7a977782..00000000 --- a/docs/_pages/docs/03-understand/11-api.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -layout: single -title: RoboSats API V1 -permalink: /docs/api-v1/ -sidebar: - title: 'API' - nav: docs -toc: true -toc_sticky: true -src: "_pages/docs/03-understand/11-api.md" ---- - -{% include wip %} \ No newline at end of file diff --git a/docs/assets/schemas/api-v0.1.yaml b/docs/assets/schemas/api-v0.1.yaml new file mode 100644 index 00000000..e5f4c8e1 --- /dev/null +++ b/docs/assets/schemas/api-v0.1.yaml @@ -0,0 +1,1776 @@ +openapi: 3.0.3 +info: + title: RoboSats REST API v0 + version: 0.1.0 + x-logo: + url: https://raw.githubusercontent.com/Reckless-Satoshi/robosats/main/frontend/static/assets/images/robosats-0.1.1-banner.png + backgroundColor: '#FFFFFF' + altText: RoboSats logo + description: |2+ + + REST API Documentation for [RoboSats](https://learn.robosats.com) - A Simple and Private LN P2P Exchange + +

+ Note: + The RoboSats REST API is on v0, which in other words, is beta. + We recommend that if you don't have time to actively maintain + your project, do not build it with v0 of the API. A refactored, simpler + and more stable version - v1 will be released soon™. +

+ +paths: + /api/book/: + get: + operationId: book_list + description: Get public orders in the book. + summary: Get public orders + parameters: + - in: query + name: currency + schema: + type: integer + description: The currency id to filter by. Currency IDs can be found [here](https://github.com/Reckless-Satoshi/robosats/blob/main/frontend/static/assets/currencies.json). + Value of `0` means ANY currency + - in: query + name: type + schema: + type: integer + enum: + - 0 + - 1 + - 2 + description: |- + Order type to filter by + - `0` - BUY + - `1` - SELL + - `2` - ALL + tags: + - book + security: + - cookieAuth: [] + - basicAuth: [] + - {} + responses: + '200': + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/OrderPublic' + description: '' + /api/historical/: + get: + operationId: historical_list + description: Get historical exchange activity. Currently, it lists each day's + total contracts and their volume in BTC since inception. + summary: Get historical exchange activity + tags: + - historical + security: + - cookieAuth: [] + - basicAuth: [] + - {} + responses: + '200': + content: + application/json: + schema: + type: array + items: + type: object + additionalProperties: + type: object + properties: + volume: + type: integer + description: Total Volume traded on that particular date + num_contracts: + type: number + description: Number of successful trades on that particular + date + examples: + TruncatedExample: + value: + - : + code: USD + price: '42069.69' + min_amount: '4.2' + max_amount: '420.69' + max_bondless_amount: '10.1' + summary: Truncated example + description: '' + /api/info/: + get: + operationId: info_list + description: "\nGet general info (overview) about the exchange.\n\n**Info**:\n\ + - Current market data\n - num. of orders\n - book liquidity\n - 24h active\ + \ robots \n - 24h non-KYC premium\n - 24h volume\n - all time volume\n\ + - Node info \n - lnd version\n - node id\n - node alias\n - network\n\ + - Fees\n - maker and taker fees\n - on-chain swap fees\n- Robot (If autheticated)\n\ + \ - nickname\n - referral code\n - earned rewards\n" + summary: Get info + tags: + - info + security: + - cookieAuth: [] + - basicAuth: [] + - {} + responses: + '200': + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Info' + description: '' + /api/limits/: + get: + operationId: limits_list + description: Get a list of order limits for every currency pair available. + summary: List order limits + tags: + - limits + security: + - cookieAuth: [] + - basicAuth: [] + - {} + responses: + '200': + content: + application/json: + schema: + type: array + items: + type: object + additionalProperties: + type: object + properties: + code: + type: string + description: Three letter currency symbol + price: + type: integer + min_amount: + type: integer + description: Minimum amount allowed in an order in the particular + currency + max_amount: + type: integer + description: Maximum amount allowed in an order in the particular + currency + max_bondless_amount: + type: integer + description: Maximum amount allowed in a bondless order + examples: + TruncatedExample.RealResponseContainsAllTheCurrencies: + value: + - : + code: USD + price: '42069.69' + min_amount: '4.2' + max_amount: '420.69' + max_bondless_amount: '10.1' + summary: Truncated example. Real response contains all the currencies + description: '' + /api/make/: + post: + operationId: make_create + description: |2 + + Create a new order as a maker. + + + Default values for the following fields if not specified: + - `public_duration` - **86399** + - `escrow_duration` - **1800** + - `bond_size` - **3** + - `bondless_taker` - **false** + - `has_range` - **false** + - `premium` - **0** + summary: Create a maker order + tags: + - make + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/MakeOrder' + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/MakeOrder' + multipart/form-data: + schema: + $ref: '#/components/schemas/MakeOrder' + required: true + security: + - cookieAuth: [] + - basicAuth: [] + - {} + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/ListOrder' + description: '' + '400': + content: + application/json: + schema: + type: object + properties: + bad_request: + type: string + description: Reason for the failure + description: '' + '409': + content: + application/json: + schema: + type: object + properties: + bad_request: + type: string + description: Reason for the failure + description: '' + /api/order/: + get: + operationId: order_retrieve + description: |2+ + + Get the order details. Details include/exclude attributes according to what is the status of the order + + The following fields are available irrespective of whether you are a participant or not (A participant is either a taker or a maker of an order) + All the other fields are only available when you are either the taker or the maker of the order: + + - `id` + - `status` + - `created_at` + - `expires_at` + - `type` + - `currency` + - `amount` + - `has_range` + - `min_amount` + - `max_amount` + - `payment_method` + - `is_explicit` + - `premium` + - `satoshis` + - `bondless_taker` + - `maker` + - `taker` + - `escrow_duration` + - `total_secs_exp` + - `penalty` + - `is_maker` + - `is_taker` + - `is_participant` + - `maker_status` + - `taker_status` + - `price_now` + + ### Order Status + + The response of this route changes according to the status of the order. Some fields are documented below (check the 'Responses' section) + with the status code of when they are available and some or not. With v1 API we aim to simplify this + route to make it easier to understand which fields are available on which order status codes. + + `status` specifies the status of the order. Below is a list of possible values (status codes) and what they mean: + - `0` "Waiting for maker bond" + - `1` "Public" + - `2` "Paused" + - `3` "Waiting for taker bond" + - `4` "Cancelled" + - `5` "Expired" + - `6` "Waiting for trade collateral and buyer invoice" + - `7` "Waiting only for seller trade collateral" + - `8` "Waiting only for buyer invoice" + - `9` "Sending fiat - In chatroom" + - `10` "Fiat sent - In chatroom" + - `11` "In dispute" + - `12` "Collaboratively cancelled" + - `13` "Sending satoshis to buyer" + - `14` "Sucessful trade" + - `15` "Failed lightning network routing" + - `16` "Wait for dispute resolution" + - `17` "Maker lost dispute" + - `18` "Taker lost dispute" + + + Notes: + - both `price_now` and `premium_now` are always calculated irrespective of whether `is_explicit` = true or false + + summary: Get order details + parameters: + - in: query + name: order_id + schema: + type: integer + required: true + tags: + - order + security: + - cookieAuth: [] + - basicAuth: [] + - {} + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/OrderDetail' + description: '' + '400': + content: + application/json: + schema: + type: object + properties: + bad_request: + type: string + description: Reason for the failure + examples: + OrderCancelled: + value: + bad_request: This order has been cancelled collaborativelly + summary: Order cancelled + WhenTheOrderIsNotPublicAndYouNeitherTheTakerNorMaker: + value: + bad_request: This order is not available + summary: When the order is not public and you neither the taker + nor maker + WhenMakerBondExpires(asMaker): + value: + bad_request: Invoice expired. You did not confirm publishing the + order in time. Make a new order. + summary: When maker bond expires (as maker) + WhenRobosatsNodeIsDown: + value: + bad_request: The Lightning Network Daemon (LND) is down. Write + in the Telegram group to make sure the staff is aware. + summary: When Robosats node is down + description: '' + '403': + content: + application/json: + schema: + type: object + properties: + bad_request: + type: string + description: Reason for the failure + default: This order is not available + description: '' + '404': + content: + application/json: + schema: + type: object + properties: + bad_request: + type: string + description: Reason for the failure + default: Invalid order Id + description: '' + post: + operationId: order_create + description: |2+ + + Update an order + + `action` field is required and determines what is to be done. Below + is an explaination of what each action does: + + - `take` + - If the order has not expired and is still public, on a + successful take, you get the same response as if `GET /order` + was called and the status of the order was `3` (waiting for + taker bond) which means `bond_satoshis` and `bond_invoice` are + present in the response as well. Once the `bond_invoice` is + paid, you successfully become the taker of the order and the + status of the order changes. + - `pause` + - Toggle the status of an order from `1` to `2` and vice versa. Allowed only if status is `1` (Public) or `2` (Paused) + - `update_invoice` + - This action only is valid if you are the buyer. The `invoice` + field needs to be present in the body and the value must be a + valid LN invoice. Make sure to perform this action only when + both the bonds are locked. i.e The status of your order is + atleast `6` (Waiting for trade collateral and buyer invoice) + - `update_address` + - This action is only valid if you are the buyer. This action is + used to set an on-chain payout address if you wish to have your + payout be recieved on-chain. This enables on-chain swap for the + order, so even if you earlier had submitted a LN invoice, it + will be ignored. You get to choose the `mining_fee_rate` as + well. Mining fee rate is specified in sats/vbyte. + - `cancel` + - This action is used to cancel an existing order. You cannot cancel an order if it's in one of the following states: + - `1` - Cancelled + - `5` - Expired + - `11` - In dispute + - `12` - Collaboratively cancelled + - `13` - Sending satoshis to buyer + - `14` - Sucessful trade + - `15` - Failed lightning network routing + - `17` - Maker lost dispute + - `18` - Taker lost dispute + + Note that there are penalties involved for cancelling a order + mid-trade so use this action carefully: + + - As a maker if you cancel an order after you have locked your + maker bond, you are returend your bond. This may change in + the future to prevent DDoSing the LN node and you won't be + returend the maker bond. + - As a taker there is a time penalty involved if you `take` an + order and cancel it without locking the taker bond. + - For both taker or maker, if you cancel the order when both + have locked thier bonds (status = `6` or `7`), you loose your + bond and a percent of it goes as "rewards" to your + counterparty and some of it the platform keeps. This is to + discourage wasting time and DDoSing the platform. + - For both taker or maker, if you cancel the order when the + escrow is locked (status = `8` or `9`), you trigger a + collaborative cancel request. This sets + `(m|t)aker_asked_cancel` field to `true` depending on whether + you are the maker or the taker respectively, so that your + counterparty is informed that you asked for a cancel. + - For both taker or maker, and your counterparty asked for a + cancel (i.e `(m|t)aker_asked_cancel` is true), and you cancel + as well, a collaborative cancel takes place which returns + both the bonds and escrow to the respective parties. Note + that in the future there will be a cost for even + collaborativelly cancelling orders for both parties. + - `confirm` + - This is a **crucial** action. This confirms the sending and + recieving of fiat depending on whether you are a buyer or + seller. There is not much RoboSats can do to actually confirm + and verify the fiat payment channel. It is up to you to make + sure of the correct amount was recieved before you confirm. + This action is only allowed when status is either `9` (Sending + fiat - In chatroom) or `10` (Fiat sent - In chatroom) + - If you are the buyer, it simply sets `fiat_sent` to `true` + which means that you have sent the fiat using the payment + method selected by the seller and signals the seller that the + fiat payment was done. + - If you are the seller, be very careful and double check + before perorming this action. Check that your fiat payment + method was successful in recieving the funds and whether it + was the correct amount. This action settles the escrow and + pays the buyer and sets the the order status to `13` (Sending + satohis to buyer) and eventually to `14` (successful trade). + - `dispute` + - This action is allowed only if status is `9` or `10`. It sets + the order status to `11` (In dispute) and sets `is_disputed` to + `true`. Both the bonds and the escrow are settled (i.e RoboSats + takes custody of the funds). Disputes can take long to resolve, + it might trigger force closure for unresolved HTLCs). Dispute + winner will have to submit a new invoice for value of escrow + + bond. + - `submit_statement` + - This action updates the dispute statement. Allowed only when + status is `11` (In dispute). `satement` must be sent in the + request body and should be a string. 100 chars < length of + `statement` < 5000 chars. You need to discribe the reason for + raising a dispute. The `(m|t)aker_statement` field is set + respectively. Only when both parties have submitted thier + dispute statement, the order status changes to `16` (Waiting + for dispute resolution) + - `rate_user` + - You can rate your counterparty using this action. You can rate + your user from `1-5` using the `rate` field in the request + body. Only allowed in the following states: + - `13` - Sending satoshis to buyer + - `14` - Sucessful trade + - `15` - Failed lightning network routing + - `17` - Maker lost dispute + - `18` - Taker lost dispute + - `rate_platform` + - Let us know how much you love (or hate 😢) RoboSats. + You can rate the platform from `1-5` using the `rate` field in the request body + + summary: Update order + parameters: + - in: query + name: order_id + schema: + type: integer + required: true + tags: + - order + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateOrder' + examples: + UserNotAuthenticated: + value: + bad_request: Woops! It seems you do not have a robot avatar + summary: User not authenticated + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/UpdateOrder' + multipart/form-data: + schema: + $ref: '#/components/schemas/UpdateOrder' + required: true + security: + - cookieAuth: [] + - basicAuth: [] + - {} + responses: + '200': + content: + application/json: + schema: + type: object + additionalProperties: + oneOf: + - type: str + - type: number + - type: object + - type: boolean + description: '' + '400': + content: + application/json: + schema: + type: object + properties: + bad_request: + type: string + description: Reason for the failure + examples: + UserNotAuthenticated: + value: + bad_request: Woops! It seems you do not have a robot avatar + summary: User not authenticated + description: '' + /api/price/: + get: + operationId: price_list + description: Get the last market price for each currency. Also, returns some + more info about the last trade in each currency. + summary: Get last market prices + tags: + - price + security: + - cookieAuth: [] + - basicAuth: [] + - {} + responses: + '200': + content: + application/json: + schema: + type: array + items: + type: object + additionalProperties: + type: object + properties: + price: + type: integer + volume: + type: integer + premium: + type: integer + timestamp: + type: string + format: date-time + examples: + TruncatedExample.RealResponseContainsAllTheCurrencies: + value: + - : + price: 21948.89 + volume: 0.01366812 + premium: 3.5 + timestamp: '2022-09-13T14:32:40.591774Z' + summary: Truncated example. Real response contains all the currencies + description: '' + /api/reward/: + post: + operationId: reward_create + description: Withdraw user reward by submitting an invoice + summary: Withdraw reward + tags: + - reward + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ClaimReward' + examples: + UserNotAuthenticated: + value: + bad_request: Woops! It seems you do not have a robot avatar + summary: User not authenticated + WhenNoRewardsEarned: + value: + successful_withdrawal: false + bad_invoice: You have not earned rewards + summary: When no rewards earned + BadInvoiceOrInCaseOfPaymentFailure: + value: + successful_withdrawal: false + bad_invoice: Does not look like a valid lightning invoice + summary: Bad invoice or in case of payment failure + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/ClaimReward' + multipart/form-data: + schema: + $ref: '#/components/schemas/ClaimReward' + security: + - cookieAuth: [] + - basicAuth: [] + - {} + responses: + '200': + content: + application/json: + schema: + type: object + properties: + successful_withdrawal: + type: boolean + default: true + description: '' + '400': + content: + application/json: + schema: + oneOf: + - type: object + properties: + successful_withdrawal: + type: boolean + default: false + bad_invoice: + type: string + description: More context for the reason of the failure + - type: object + properties: + successful_withdrawal: + type: boolean + default: false + bad_request: + type: string + description: More context for the reason of the failure + examples: + UserNotAuthenticated: + value: + bad_request: Woops! It seems you do not have a robot avatar + summary: User not authenticated + WhenNoRewardsEarned: + value: + successful_withdrawal: false + bad_invoice: You have not earned rewards + summary: When no rewards earned + BadInvoiceOrInCaseOfPaymentFailure: + value: + successful_withdrawal: false + bad_invoice: Does not look like a valid lightning invoice + summary: Bad invoice or in case of payment failure + description: '' + /api/stealth/: + put: + operationId: stealth_update + description: Update stealth invoice option for the user + summary: Update stealth option + tags: + - stealth + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Stealth' + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/Stealth' + multipart/form-data: + schema: + $ref: '#/components/schemas/Stealth' + required: true + security: + - cookieAuth: [] + - basicAuth: [] + - {} + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Stealth' + description: '' + '400': + content: + application/json: + schema: + type: object + properties: + bad_request: + type: string + description: Reason for the failure + description: '' + patch: + operationId: stealth_partial_update + tags: + - stealth + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/PatchedStealth' + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/PatchedStealth' + multipart/form-data: + schema: + $ref: '#/components/schemas/PatchedStealth' + security: + - cookieAuth: [] + - basicAuth: [] + - {} + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Stealth' + description: '' + /api/ticks/: + get: + operationId: ticks_list + description: |- + Get all market ticks. Returns a list of all the market ticks since inception. + CEX price is also recorded for useful insight on the historical premium of Non-KYC BTC. Price is set when taker bond is locked. + summary: Get market ticks + tags: + - ticks + security: + - cookieAuth: [] + - basicAuth: [] + - {} + responses: + '200': + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Tick' + description: '' + /api/user/: + post: + operationId: user_create + description: |- + Get a new user derived from a high entropy token + + - Request has a hash of a high-entropy token + - Request includes pubKey and encrypted privKey + - Generates new nickname and avatar. + - Creates login credentials (new User object) + + Response with Avatar, Nickname, pubKey, privKey. + tags: + - user + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/UserGen' + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/UserGen' + multipart/form-data: + schema: + $ref: '#/components/schemas/UserGen' + required: true + security: + - cookieAuth: [] + - basicAuth: [] + - {} + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/UserGen' + description: '' + delete: + operationId: user_destroy + description: |2 + + Delete a Robot. Deleting a robot is not allowed if the robot has an active order, has had completed trades or was created more than 30 mins ago. + Mainly used on the frontend to "Generate new Robot" without flooding the DB with discarded robots. + summary: Delete user + tags: + - user + security: + - cookieAuth: [] + - basicAuth: [] + - {} + responses: + '403': + description: No response body + '400': + content: + application/json: + schema: + type: object + properties: + bad_request: + type: string + description: Reason for the failure + description: '' + '301': + content: + application/json: + schema: + type: object + properties: + user_deleted: + type: string + default: User deleted permanently + description: '' +components: + schemas: + ActionEnum: + enum: + - pause + - take + - update_invoice + - update_address + - submit_statement + - dispute + - cancel + - confirm + - rate_user + - rate_platform + type: string + BlankEnum: + enum: + - '' + ClaimReward: + type: object + properties: + invoice: + type: string + nullable: true + description: A valid LN invoice with the reward amount to withdraw + maxLength: 2000 + CurrencyEnum: + enum: + - 1 + - 2 + - 3 + - 4 + - 5 + - 6 + - 7 + - 8 + - 9 + - 10 + - 11 + - 12 + - 13 + - 14 + - 15 + - 16 + - 17 + - 18 + - 19 + - 20 + - 21 + - 22 + - 23 + - 24 + - 25 + - 26 + - 27 + - 28 + - 29 + - 30 + - 31 + - 32 + - 33 + - 34 + - 35 + - 36 + - 37 + - 38 + - 39 + - 40 + - 41 + - 42 + - 43 + - 44 + - 45 + - 46 + - 47 + - 48 + - 49 + - 50 + - 51 + - 52 + - 53 + - 54 + - 55 + - 56 + - 57 + - 58 + - 59 + - 60 + - 61 + - 62 + - 63 + - 64 + - 65 + - 66 + - 67 + - 68 + - 69 + - 300 + - 1000 + type: integer + ExpiryReasonEnum: + enum: + - 0 + - 1 + - 2 + - 3 + - 4 + type: integer + Info: + type: object + properties: + num_public_buy_orders: + type: integer + num_public_sell_orders: + type: integer + book_liquidity: + type: integer + description: Total amount of BTC in the order book + active_robots_today: + type: string + last_day_nonkyc_btc_premium: + type: number + format: double + description: Average premium (weighted by volume) of the orders in the last + 24h + last_day_volume: + type: number + format: double + description: Total volume in BTC in the last 24h + lifetime_volume: + type: number + format: double + description: Total volume in BTC since exchange's inception + lnd_version: + type: string + robosats_running_commit_hash: + type: string + alternative_site: + type: string + alternative_name: + type: string + node_alias: + type: string + node_id: + type: string + network: + type: string + maker_fee: + type: number + format: double + description: Exchange's set maker fee + taker_fee: + type: number + format: double + description: 'Exchange''s set taker fee ' + bond_size: + type: number + format: double + description: Default bond size (percent) + current_swap_fee_rate: + type: number + format: double + description: Swap fees to perform on-chain transaction (percent) + nickname: + type: string + description: Currenlty logged in Robot name + referral_code: + type: string + description: Logged in users's referral code + earned_rewards: + type: integer + description: Logged in user's earned rewards in satoshis + required: + - active_robots_today + - alternative_name + - alternative_site + - bond_size + - book_liquidity + - current_swap_fee_rate + - earned_rewards + - last_day_nonkyc_btc_premium + - last_day_volume + - lifetime_volume + - lnd_version + - maker_fee + - network + - nickname + - node_alias + - node_id + - num_public_buy_orders + - num_public_sell_orders + - referral_code + - robosats_running_commit_hash + - taker_fee + ListOrder: + type: object + properties: + id: + type: integer + readOnly: true + status: + allOf: + - $ref: '#/components/schemas/StatusEnum' + minimum: 0 + maximum: 32767 + created_at: + type: string + format: date-time + expires_at: + type: string + format: date-time + type: + allOf: + - $ref: '#/components/schemas/TypeEnum' + minimum: 0 + maximum: 32767 + currency: + type: integer + nullable: true + amount: + type: string + format: decimal + pattern: ^-?\d{0,10}(?:\.\d{0,8})?$ + nullable: true + has_range: + type: boolean + min_amount: + type: string + format: decimal + pattern: ^-?\d{0,10}(?:\.\d{0,8})?$ + nullable: true + max_amount: + type: string + format: decimal + pattern: ^-?\d{0,10}(?:\.\d{0,8})?$ + nullable: true + payment_method: + type: string + maxLength: 70 + is_explicit: + type: boolean + premium: + type: string + format: decimal + pattern: ^-?\d{0,3}(?:\.\d{0,2})?$ + nullable: true + satoshis: + type: integer + maximum: 4000000 + minimum: 20000 + nullable: true + bondless_taker: + type: boolean + maker: + type: integer + nullable: true + taker: + type: integer + nullable: true + escrow_duration: + type: integer + maximum: 28800 + minimum: 1800 + bond_size: + type: string + format: decimal + pattern: ^-?\d{0,2}(?:\.\d{0,2})?$ + required: + - expires_at + - id + - type + MakeOrder: + type: object + properties: + type: + allOf: + - $ref: '#/components/schemas/TypeEnum' + minimum: 0 + maximum: 32767 + currency: + type: integer + description: Currency id. See [here](https://github.com/Reckless-Satoshi/robosats/blob/main/frontend/static/assets/currencies.json) + for a list of all IDs + amount: + type: string + format: decimal + pattern: ^-?\d{0,10}(?:\.\d{0,8})?$ + nullable: true + has_range: + type: boolean + default: false + description: |- + Whether the order specifies a range of amount or a fixed amount. + + If `true`, then `min_amount` and `max_amount` fields are **required**. + + If `false` then `amount` is **required** + min_amount: + type: string + format: decimal + pattern: ^-?\d{0,10}(?:\.\d{0,8})?$ + nullable: true + max_amount: + type: string + format: decimal + pattern: ^-?\d{0,10}(?:\.\d{0,8})?$ + nullable: true + payment_method: + type: string + default: not specified + description: Can be any string. The UI recognizes [these payment methods](https://github.com/Reckless-Satoshi/robosats/blob/main/frontend/src/components/payment-methods/Methods.js) + and displays them with a logo. + maxLength: 70 + is_explicit: + type: boolean + default: false + description: Whether the order is explicitly priced or not. If set to `true` + then `satoshis` need to be specified + premium: + type: string + format: decimal + pattern: ^-?\d{0,3}(?:\.\d{0,2})?$ + nullable: true + satoshis: + type: integer + maximum: 4000000 + minimum: 20000 + nullable: true + public_duration: + type: integer + maximum: 86400.0 + minimum: 597.6 + escrow_duration: + type: integer + maximum: 28800 + minimum: 1800 + bond_size: + type: string + format: decimal + pattern: ^-?\d{0,2}(?:\.\d{0,2})?$ + bondless_taker: + type: boolean + default: false + description: Whether bondless takers are allowed for this order or not + required: + - currency + - type + Nested: + type: object + properties: + id: + type: integer + readOnly: true + currency: + allOf: + - $ref: '#/components/schemas/CurrencyEnum' + minimum: 0 + maximum: 32767 + exchange_rate: + type: string + format: decimal + pattern: ^-?\d{0,10}(?:\.\d{0,4})?$ + nullable: true + timestamp: + type: string + format: date-time + required: + - currency + - id + NullEnum: + enum: + - null + OrderDetail: + type: object + properties: + id: + type: integer + readOnly: true + status: + allOf: + - $ref: '#/components/schemas/StatusEnum' + minimum: 0 + maximum: 32767 + created_at: + type: string + format: date-time + expires_at: + type: string + format: date-time + type: + allOf: + - $ref: '#/components/schemas/TypeEnum' + minimum: 0 + maximum: 32767 + currency: + type: integer + nullable: true + amount: + type: string + format: decimal + pattern: ^-?\d{0,10}(?:\.\d{0,8})?$ + nullable: true + has_range: + type: boolean + min_amount: + type: string + format: decimal + pattern: ^-?\d{0,10}(?:\.\d{0,8})?$ + nullable: true + max_amount: + type: string + format: decimal + pattern: ^-?\d{0,10}(?:\.\d{0,8})?$ + nullable: true + payment_method: + type: string + maxLength: 70 + is_explicit: + type: boolean + premium: + type: integer + description: Premium over the CEX price at the current time + satoshis: + type: integer + maximum: 4000000 + minimum: 20000 + nullable: true + bondless_taker: + type: boolean + maker: + type: integer + nullable: true + taker: + type: integer + nullable: true + escrow_duration: + type: integer + maximum: 28800 + minimum: 1800 + total_secs_exp: + type: integer + description: Duration of time (in seconds) to expire, according to the current + status of order.This is duration of time after `created_at` (in seconds) + that the order will automatically expire.This value changes according + to which stage the order is in + penalty: + type: string + format: date-time + description: Time when the user penalty will expire. Penalty applies when + you create orders repeatedly without commiting a bond + is_maker: + type: boolean + description: Whether you are the maker or not + is_taker: + type: boolean + description: Whether you are the taker or not + is_participant: + type: boolean + description: True if you are either a taker or maker, False otherwise + maker_status: + type: string + description: |- + Status of the maker: + - **'Active'** (seen within last 2 min) + - **'Seen Recently'** (seen within last 10 min) + - **'Inactive'** (seen more than 10 min ago) + + Note: When you make a request to this route, your own status get's updated and can be seen by your counterparty + taker_status: + type: boolean + description: True if you are either a taker or maker, False otherwise + price_now: + type: integer + description: Price of the order in the order's currency at the time of request + (upto 5 significant digits) + premium_percentile: + type: integer + description: (Only if `is_maker`) Premium percentile of your order compared + to other public orders in the same currency currently in the order book + num_similar_orders: + type: integer + description: (Only if `is_maker`) The number of public orders of the same + currency currently in the order book + tg_enabled: + type: boolean + description: (Only if `is_maker`) Whether Telegram notification is enabled + or not + tg_token: + type: string + description: (Only if `is_maker`) Your telegram bot token required to enable + notifications. + tg_bot_name: + type: string + description: (Only if `is_maker`) The Telegram username of the bot + is_buyer: + type: boolean + description: Whether you are a buyer of sats (you will be receiving sats) + is_seller: + type: boolean + description: Whether you are a seller of sats or not (you will be sending + sats) + maker_nick: + type: string + description: Nickname (Robot name) of the maker + taker_nick: + type: string + description: Nickname (Robot name) of the taker + status_message: + type: string + description: The current status of the order corresponding to the `status` + is_fiat_sent: + type: boolean + description: Whether or not the fiat amount is sent by the buyer + is_disputed: + type: boolean + description: Whether or not the counterparty raised a dispute + ur_nick: + type: string + description: Your Nick + maker_locked: + type: boolean + description: True if maker bond is locked, False otherwise + taker_locked: + type: boolean + description: True if taker bond is locked, False otherwise + escrow_locked: + type: boolean + description: True if escrow is locked, False otherwise. Escrow is the sats + to be sold, held by Robosats until the trade is finised. + trade_satoshis: + type: integer + description: 'Seller sees the amount of sats they need to send. Buyer sees + the amount of sats they will receive ' + bond_invoice: + type: string + description: When `status` = `0`, `3`. Bond invoice to be paid + bond_satoshis: + type: integer + description: The bond amount in satoshis + escrow_invoice: + type: string + description: For the seller, the escrow invoice to be held by RoboSats + escrow_satoshis: + type: integer + description: The escrow amount in satoshis + invoice_amount: + type: integer + description: The amount in sats the buyer needs to submit an invoice of + to receive the trade amount + swap_allowed: + type: boolean + description: Whether on-chain swap is allowed + swap_failure_reason: + type: string + description: Reason for why on-chain swap is not available + suggested_mining_fee_rate: + type: integer + description: fee in sats/vbyte for the on-chain swap + swap_fee_rate: + type: number + format: double + description: in percentage, the swap fee rate the platform charges + pending_cancel: + type: boolean + description: Your counterparty requested for a collaborative cancel when + `status` is either `8`, `9` or `10` + asked_for_cancel: + type: boolean + description: You requested for a collaborative cancel `status` is either + `8`, `9` or `10` + statement_submitted: + type: boolean + description: True if you have submitted a statement. Available when `status` + is `11` + retries: + type: integer + description: Number of times ln node has tried to make the payment to you + (only if you are the buyer) + next_retry_time: + type: string + format: date-time + description: The next time payment will be retried. Payment is retried every + 1 sec + failure_reason: + type: string + description: The reason the payout failed + invoice_expired: + type: boolean + description: True if the payout invoice expired. `invoice_amount` will be + re-set and sent which means the user has to submit a new invoice to be + payed + public_duration: + type: integer + maximum: 86400.0 + minimum: 597.6 + bond_size: + type: string + format: decimal + pattern: ^-?\d{0,2}(?:\.\d{0,2})?$ + trade_fee_percent: + type: integer + description: The fee for the trade (fees differ for maker and taker) + bond_size_sats: + type: integer + description: The size of the bond in sats + bond_size_percent: + type: integer + description: same as `bond_size` + maker_summary: + $ref: '#/components/schemas/Summary' + taker_summary: + $ref: '#/components/schemas/Summary' + platform_summary: + $ref: '#/components/schemas/PlatformSummary' + expiry_reason: + nullable: true + minimum: 0 + maximum: 32767 + oneOf: + - $ref: '#/components/schemas/ExpiryReasonEnum' + - $ref: '#/components/schemas/NullEnum' + expiry_message: + type: string + description: The reason the order expired (message associated with the `expiry_reason`) + num_satoshis: + type: integer + description: only if status = `14` (Successful Trade) and is_buyer = `true` + sent_satoshis: + type: integer + description: only if status = `14` (Successful Trade) and is_buyer = `true` + txid: + type: string + description: Transaction id of the on-chain swap payout. Only if status + = `14` (Successful Trade) and is_buyer = `true` + network: + type: string + description: The network eg. 'testnet', 'mainnet'. Only if status = `14` + (Successful Trade) and is_buyer = `true` + required: + - expires_at + - id + - platform_summary + - type + OrderPublic: + type: object + properties: + id: + type: integer + readOnly: true + created_at: + type: string + format: date-time + expires_at: + type: string + format: date-time + type: + allOf: + - $ref: '#/components/schemas/TypeEnum' + minimum: 0 + maximum: 32767 + currency: + type: integer + nullable: true + amount: + type: string + format: decimal + pattern: ^-?\d{0,10}(?:\.\d{0,8})?$ + nullable: true + has_range: + type: boolean + min_amount: + type: string + format: decimal + pattern: ^-?\d{0,10}(?:\.\d{0,8})?$ + nullable: true + max_amount: + type: string + format: decimal + pattern: ^-?\d{0,10}(?:\.\d{0,8})?$ + nullable: true + payment_method: + type: string + maxLength: 70 + is_explicit: + type: boolean + premium: + type: string + format: decimal + pattern: ^-?\d{0,3}(?:\.\d{0,2})?$ + nullable: true + satoshis: + type: integer + maximum: 4000000 + minimum: 20000 + nullable: true + bondless_taker: + type: boolean + maker: + type: integer + nullable: true + maker_nick: + type: string + maker_status: + type: string + description: Status of the nick - "Active" or "Inactive" + price: + type: integer + description: Price in order's fiat currency + escrow_duration: + type: integer + maximum: 28800 + minimum: 1800 + required: + - expires_at + - id + - type + PatchedStealth: + type: object + properties: + wantsStealth: + type: boolean + PlatformSummary: + type: object + properties: + contract_timestamp: + type: string + format: date-time + description: Timestamp of when the contract was finalized (price and sats + fixed) + contract_total_time: + type: number + format: double + description: The time taken for the contract to complete (from taker taking + the order to completion of order) in seconds + routing_fee_sats: + type: integer + description: Sats payed by the exchange for routing fees. Mining fee in + case of on-chain swap payout + trade_revenue_sats: + type: integer + description: The sats the exchange earned from the trade + RatingEnum: + enum: + - '1' + - '2' + - '3' + - '4' + - '5' + type: string + StatusEnum: + enum: + - 0 + - 1 + - 2 + - 3 + - 4 + - 5 + - 6 + - 7 + - 8 + - 9 + - 10 + - 11 + - 12 + - 13 + - 14 + - 15 + - 16 + - 17 + - 18 + type: integer + Stealth: + type: object + properties: + wantsStealth: + type: boolean + required: + - wantsStealth + Summary: + type: object + properties: + sent_fiat: + type: integer + description: same as `amount` (only for buyer) + received_sats: + type: integer + description: same as `trade_satoshis` (only for buyer) + is_swap: + type: boolean + description: True if the payout was on-chain (only for buyer) + received_onchain_sats: + type: integer + description: The on-chain sats received (only for buyer and if `is_swap` + is `true`) + mining_fee_sats: + type: integer + description: Mining fees paid in satoshis (only for buyer and if `is_swap` + is `true`) + swap_fee_sats: + type: integer + description: Exchange swap fee in sats (i.e excluding miner fees) (only + for buyer and if `is_swap` is `true`) + swap_fee_percent: + type: number + format: double + description: same as `swap_fee_rate` (only for buyer and if `is_swap` is + `true` + sent_sats: + type: integer + description: The total sats you sent (only for seller) + received_fiat: + type: integer + description: same as `amount` (only for seller) + trade_fee_sats: + type: integer + description: Exchange fees in sats (Does not include swap fee and miner + fee) + Tick: + type: object + properties: + timestamp: + type: string + format: date-time + currency: + allOf: + - $ref: '#/components/schemas/Nested' + readOnly: true + volume: + type: string + format: decimal + nullable: true + price: + type: string + format: decimal + pattern: ^-?\d{0,14}(?:\.\d{0,2})?$ + nullable: true + premium: + type: string + format: decimal + pattern: ^-?\d{0,3}(?:\.\d{0,2})?$ + nullable: true + fee: + type: string + format: decimal + required: + - currency + TypeEnum: + enum: + - 0 + - 1 + type: integer + UpdateOrder: + type: object + properties: + invoice: + type: string + nullable: true + maxLength: 2000 + address: + type: string + nullable: true + maxLength: 100 + statement: + type: string + nullable: true + maxLength: 10000 + action: + $ref: '#/components/schemas/ActionEnum' + rating: + nullable: true + oneOf: + - $ref: '#/components/schemas/RatingEnum' + - $ref: '#/components/schemas/BlankEnum' + - $ref: '#/components/schemas/NullEnum' + amount: + type: string + format: decimal + pattern: ^-?\d{0,10}(?:\.\d{0,8})?$ + nullable: true + mining_fee_rate: + type: string + format: decimal + pattern: ^-?\d{0,3}(?:\.\d{0,3})?$ + nullable: true + required: + - action + UserGen: + type: object + properties: + token_sha256: + type: string + description: SHA256 of user secret + maxLength: 64 + minLength: 64 + public_key: + type: string + description: Armored ASCII PGP public key block + maxLength: 2000 + encrypted_private_key: + type: string + description: Armored ASCII PGP encrypted private key block + maxLength: 2000 + ref_code: + type: string + nullable: true + description: Referal code + maxLength: 30 + counts: + type: array + items: + type: integer + nullable: true + description: Counts of the unique characters in the token + length: + type: integer + minimum: 1 + nullable: true + description: Length of the token + unique_values: + type: integer + minimum: 1 + nullable: true + description: Number of unique values in the token + required: + - encrypted_private_key + - public_key + - token_sha256 + securitySchemes: + basicAuth: + type: http + scheme: basic + cookieAuth: + type: apiKey + in: cookie + name: sessionid