mirror of
https://github.com/RoboSats/robosats.git
synced 2024-12-13 19:06:26 +00:00
2020 lines
64 KiB
YAML
2020 lines
64 KiB
YAML
openapi: 3.0.3
|
|
info:
|
|
title: RoboSats REST API
|
|
version: 0.7.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
|
|
|
|
<p style='background-color:#fff0f0;padding:16px;border-radius:6px;border:2px solid #ffd3d3'>
|
|
<span style='color:#f31f1f;font-weight:bold'>Note:</span>
|
|
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™.
|
|
</p>
|
|
|
|
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/RoboSats/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:
|
|
- tokenAuth: []
|
|
- {}
|
|
responses:
|
|
'200':
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/OrderPublic'
|
|
description: ''
|
|
/api/chat/:
|
|
get:
|
|
operationId: chat_retrieve
|
|
description: Returns chat messages for an order with an index higher than `offset`.
|
|
parameters:
|
|
- in: query
|
|
name: offset
|
|
schema:
|
|
type: integer
|
|
- in: query
|
|
name: order_id
|
|
schema:
|
|
type: integer
|
|
tags:
|
|
- chat
|
|
security:
|
|
- tokenAuth: []
|
|
responses:
|
|
'200':
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Chat'
|
|
description: ''
|
|
post:
|
|
operationId: chat_create
|
|
description: Adds one new message to the chatroom. If `offset` is given, will
|
|
return every new message as well.
|
|
tags:
|
|
- chat
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/PostMessage'
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
$ref: '#/components/schemas/PostMessage'
|
|
multipart/form-data:
|
|
schema:
|
|
$ref: '#/components/schemas/PostMessage'
|
|
required: true
|
|
security:
|
|
- tokenAuth: []
|
|
responses:
|
|
'200':
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Chat'
|
|
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:
|
|
- tokenAuth: []
|
|
- {}
|
|
responses:
|
|
'200':
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: object
|
|
additionalProperties:
|
|
type: object
|
|
properties:
|
|
volume:
|
|
type: number
|
|
description: Total Volume traded on that particular date
|
|
num_contracts:
|
|
type: integer
|
|
description: Number of successful trades on that particular
|
|
date
|
|
examples:
|
|
TruncatedExample:
|
|
value:
|
|
- <date>:
|
|
volume: 0.69
|
|
num_contracts: 69
|
|
summary: Truncated example
|
|
description: ''
|
|
/api/info/:
|
|
get:
|
|
operationId: info_retrieve
|
|
description: |2
|
|
|
|
Get general info (overview) about the exchange.
|
|
|
|
**Info**:
|
|
- Current market data
|
|
- num. of orders
|
|
- book liquidity
|
|
- 24h active robots
|
|
- 24h non-KYC premium
|
|
- 24h volume
|
|
- all time volume
|
|
- Node info
|
|
- lnd version
|
|
- node id
|
|
- node alias
|
|
- network
|
|
- Fees
|
|
- maker and taker fees
|
|
- on-chain swap fees
|
|
summary: Get info
|
|
tags:
|
|
- info
|
|
security:
|
|
- tokenAuth: []
|
|
- {}
|
|
responses:
|
|
'200':
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$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:
|
|
- tokenAuth: []
|
|
- {}
|
|
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
|
|
examples:
|
|
TruncatedExample.RealResponseContainsAllTheCurrencies:
|
|
value:
|
|
- <currency number>:
|
|
code: USD
|
|
price: '42069.69'
|
|
min_amount: '4.2'
|
|
max_amount: '420.69'
|
|
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` - **24**
|
|
- `escrow_duration` - **180**
|
|
- `bond_size` - **3.0**
|
|
- `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:
|
|
- tokenAuth: []
|
|
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/notifications/:
|
|
get:
|
|
operationId: notifications_list
|
|
description: Get a list of notifications sent to the robot.
|
|
summary: Get robot notifications
|
|
parameters:
|
|
- in: query
|
|
name: created_at
|
|
schema:
|
|
type: string
|
|
description: Shows notifications created AFTER this date.
|
|
tags:
|
|
- notifications
|
|
security:
|
|
- tokenAuth: []
|
|
responses:
|
|
'200':
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/ListNotification'
|
|
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`
|
|
- `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` "Successful 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:
|
|
- tokenAuth: []
|
|
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 explanation 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 as cleartext PGP message signed (SHA512) with the robot key.
|
|
The amount of the invoice should be `invoice_amount` minus the routing
|
|
budget whose parts per million should be specified by `routing_budget_ppm`.
|
|
Make sure to perform this action only when
|
|
both the bonds are locked. i.e The status of your order is
|
|
at least `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 received on-chain. Only valid if there is an address in the body as
|
|
cleartext PGP message signed (SHA512) with the robot key. 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` - Successful 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 returned your 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 their 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
|
|
receiving 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 received 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 performing this action. Check that your fiat payment
|
|
method was successful in receiving 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).
|
|
- `undo_confirm`
|
|
- This action will undo the fiat_sent confirmation by the buyer
|
|
it is allowed only once the fiat is confirmed as sent and can
|
|
enable the collaborative cancellation option if an off-robosats
|
|
payment cannot be completed or is blocked.
|
|
- `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). `statement` must be sent in the
|
|
request body and should be a string. 100 chars < length of
|
|
`statement` < 5000 chars. You need to describe the reason for
|
|
raising a dispute. The `(m|t)aker_statement` field is set
|
|
respectively. Only when both parties have submitted their
|
|
dispute statement, the order status changes to `16` (Waiting
|
|
for dispute resolution)
|
|
- `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:
|
|
- tokenAuth: []
|
|
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:
|
|
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:
|
|
- tokenAuth: []
|
|
- {}
|
|
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:
|
|
- <currency symbol>:
|
|
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. The invoice must
|
|
be send as cleartext PGP message signed (SHA512) with the robot key
|
|
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:
|
|
- tokenAuth: []
|
|
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/robot/:
|
|
get:
|
|
operationId: robot_retrieve
|
|
description: |2+
|
|
|
|
Get robot info 🤖
|
|
|
|
An authenticated request (has the token's sha256 hash encoded as base 91 in the Authorization header) will be
|
|
returned the information about the state of a robot.
|
|
|
|
Make sure you generate your token using cryptographically secure methods.
|
|
Since the server only receives the hash of the
|
|
token, it is responsibility of the client to create a strong token. Check
|
|
[here](https://github.com/RoboSats/robosats/blob/main/frontend/src/utils/token.ts)
|
|
to see how the Javascript client creates a random strong token and how it validates entropy is optimal for tokens
|
|
created by the user at will.
|
|
The PGP key should be an EdDSA ed25519/cert,sign+cv25519/encr key.
|
|
|
|
`public_key` - PGP key associated with the user (Armored ASCII format)
|
|
`encrypted_private_key` - Private PGP key. This is only stored on the backend for later fetching by
|
|
the frontend and the key can't really be used by the server since it's protected by the token
|
|
that only the client knows. Will be made an optional parameter in a future release.
|
|
On the Javascript client, It's passphrase is set to be the secret token generated.
|
|
|
|
A gpg key can be created by:
|
|
|
|
```shell
|
|
gpg --default-new-key-algo "ed25519/cert,sign+cv25519/encr" --full-gen-key
|
|
```
|
|
|
|
it's public key can be exported in ascii armored format with:
|
|
|
|
```shell
|
|
gpg --export --armor <key-id | email | name>
|
|
```
|
|
|
|
and it's private key can be exported in ascii armored format with:
|
|
|
|
```shell
|
|
gpg --export-secret-keys --armor <key-id | email | name>
|
|
```
|
|
|
|
summary: Get robot info
|
|
tags:
|
|
- robot
|
|
security:
|
|
- tokenAuth: []
|
|
responses:
|
|
'200':
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
encrypted_private_key:
|
|
type: string
|
|
description: Armored ASCII PGP private key block
|
|
nickname:
|
|
type: string
|
|
description: Username generated (Robot name)
|
|
hash_id:
|
|
type: string
|
|
description: The hash identity of the robot, it is used to deterministically
|
|
generate the avatar and the nicknames. It is the second sha256()
|
|
of the token.
|
|
public_key:
|
|
type: string
|
|
description: Armored ASCII PGP public key block
|
|
wants_stealth:
|
|
type: boolean
|
|
default: false
|
|
description: Whether the user prefers stealth invoices
|
|
found:
|
|
type: boolean
|
|
description: Robot had been created in the past. Only if the robot
|
|
was created +5 mins ago.
|
|
tg_enabled:
|
|
type: boolean
|
|
description: The robot has telegram notifications enabled
|
|
tg_token:
|
|
type: string
|
|
description: Token to enable telegram with /start <tg_token>
|
|
tg_bot_name:
|
|
type: string
|
|
description: Name of the coordinator's telegram bot
|
|
active_order_id:
|
|
type: integer
|
|
description: Active order id if present
|
|
last_order_id:
|
|
type: integer
|
|
description: Last order id if present
|
|
earned_rewards:
|
|
type: integer
|
|
description: Satoshis available to be claimed
|
|
last_login:
|
|
type: string
|
|
format: date-time
|
|
nullable: true
|
|
description: Last time the coordinator saw this robot
|
|
examples:
|
|
SuccessfullyRetrievedRobot:
|
|
value:
|
|
nickname: SatoshiNakamoto21
|
|
public_key: |-
|
|
-----BEGIN PGP PUBLIC KEY BLOCK-----
|
|
|
|
......
|
|
......
|
|
encrypted_private_key: |-
|
|
-----BEGIN PGP PRIVATE KEY BLOCK-----
|
|
|
|
......
|
|
......
|
|
wants_stealth: true
|
|
summary: Successfully retrieved robot
|
|
description: ''
|
|
/api/stealth/:
|
|
post:
|
|
operationId: stealth_create
|
|
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:
|
|
- tokenAuth: []
|
|
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: ''
|
|
/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
|
|
parameters:
|
|
- in: query
|
|
name: end
|
|
schema:
|
|
type: string
|
|
description: End date formatted as DD-MM-YYYY
|
|
- in: query
|
|
name: start
|
|
schema:
|
|
type: string
|
|
description: Start date formatted as DD-MM-YYYY
|
|
tags:
|
|
- ticks
|
|
security:
|
|
- tokenAuth: []
|
|
- {}
|
|
responses:
|
|
'200':
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/Tick'
|
|
description: ''
|
|
components:
|
|
schemas:
|
|
ActionEnum:
|
|
enum:
|
|
- pause
|
|
- take
|
|
- update_invoice
|
|
- update_address
|
|
- submit_statement
|
|
- dispute
|
|
- cancel
|
|
- confirm
|
|
- undo_confirm
|
|
- rate_platform
|
|
type: string
|
|
description: |-
|
|
* `pause` - pause
|
|
* `take` - take
|
|
* `update_invoice` - update_invoice
|
|
* `update_address` - update_address
|
|
* `submit_statement` - submit_statement
|
|
* `dispute` - dispute
|
|
* `cancel` - cancel
|
|
* `confirm` - confirm
|
|
* `undo_confirm` - undo_confirm
|
|
* `rate_platform` - rate_platform
|
|
BlankEnum:
|
|
enum:
|
|
- ''
|
|
Chat:
|
|
type: object
|
|
properties:
|
|
messages:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/OutMessages'
|
|
offset:
|
|
type: integer
|
|
minimum: 0
|
|
nullable: true
|
|
description: Offset for message index to get as response
|
|
peer_connected:
|
|
type: boolean
|
|
description: Whether your peer has connected recently to the chatroom
|
|
peer_pubkey:
|
|
type: string
|
|
description: Your peer's public PGP key
|
|
ClaimReward:
|
|
type: object
|
|
properties:
|
|
invoice:
|
|
type: string
|
|
nullable: true
|
|
description: A valid LN invoice with the reward amount to withdraw
|
|
maxLength: 2000
|
|
ExpiryReasonEnum:
|
|
enum:
|
|
- 0
|
|
- 1
|
|
- 2
|
|
- 3
|
|
- 4
|
|
type: integer
|
|
description: |-
|
|
* `0` - Expired not taken
|
|
* `1` - Maker bond not locked
|
|
* `2` - Escrow not locked
|
|
* `3` - Invoice not submitted
|
|
* `4` - Neither escrow locked or invoice submitted
|
|
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: integer
|
|
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
|
|
cln_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
|
|
min_order_size:
|
|
type: integer
|
|
description: Minimum order size in Sats
|
|
max_order_size:
|
|
type: integer
|
|
description: Maximum order size in Sats
|
|
swap_enabled:
|
|
type: boolean
|
|
description: Whether the option for onchain swap payouts is available or
|
|
not
|
|
max_swap:
|
|
type: integer
|
|
description: Maximum size for onchain swap payouts in Sats
|
|
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)
|
|
version:
|
|
$ref: '#/components/schemas/Version'
|
|
notice_severity:
|
|
$ref: '#/components/schemas/NoticeSeverityEnum'
|
|
notice_message:
|
|
type: string
|
|
required:
|
|
- active_robots_today
|
|
- alternative_name
|
|
- alternative_site
|
|
- bond_size
|
|
- book_liquidity
|
|
- cln_version
|
|
- current_swap_fee_rate
|
|
- last_day_nonkyc_btc_premium
|
|
- last_day_volume
|
|
- lifetime_volume
|
|
- lnd_version
|
|
- maker_fee
|
|
- max_order_size
|
|
- max_swap
|
|
- min_order_size
|
|
- network
|
|
- node_alias
|
|
- node_id
|
|
- notice_message
|
|
- notice_severity
|
|
- num_public_buy_orders
|
|
- num_public_sell_orders
|
|
- robosats_running_commit_hash
|
|
- swap_enabled
|
|
- taker_fee
|
|
- version
|
|
ListNotification:
|
|
type: object
|
|
properties:
|
|
title:
|
|
type: string
|
|
maxLength: 240
|
|
description:
|
|
type: string
|
|
maxLength: 240
|
|
order_id:
|
|
type: integer
|
|
readOnly: true
|
|
status:
|
|
type: integer
|
|
readOnly: true
|
|
description: The `status` of the order when the notification was trigered
|
|
created_at:
|
|
type: string
|
|
format: date-time
|
|
required:
|
|
- order_id
|
|
- status
|
|
ListOrder:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
readOnly: true
|
|
status:
|
|
allOf:
|
|
- $ref: '#/components/schemas/StatusEnum'
|
|
default: 0
|
|
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
|
|
default: false
|
|
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
|
|
maxLength: 70
|
|
is_explicit:
|
|
type: boolean
|
|
default: false
|
|
premium:
|
|
type: string
|
|
format: decimal
|
|
pattern: ^-?\d{0,3}(?:\.\d{0,2})?$
|
|
nullable: true
|
|
default: '0.00'
|
|
satoshis:
|
|
type: integer
|
|
maximum: 5000000
|
|
minimum: 20000
|
|
nullable: true
|
|
maker:
|
|
type: integer
|
|
nullable: true
|
|
taker:
|
|
type: integer
|
|
nullable: true
|
|
escrow_duration:
|
|
type: integer
|
|
maximum: 28800
|
|
minimum: 1800
|
|
default: 10799
|
|
bond_size:
|
|
type: string
|
|
format: decimal
|
|
pattern: ^-?\d{0,2}(?:\.\d{0,2})?$
|
|
default: '3.00'
|
|
latitude:
|
|
type: string
|
|
format: decimal
|
|
pattern: ^-?\d{0,2}(?:\.\d{0,6})?$
|
|
nullable: true
|
|
longitude:
|
|
type: string
|
|
format: decimal
|
|
pattern: ^-?\d{0,3}(?:\.\d{0,6})?$
|
|
nullable: true
|
|
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/RoboSats/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/RoboSats/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
|
|
default: '0.00'
|
|
satoshis:
|
|
type: integer
|
|
maximum: 5000000
|
|
minimum: 20000
|
|
nullable: true
|
|
public_duration:
|
|
type: integer
|
|
maximum: 86400
|
|
minimum: 597.6
|
|
default: 86399
|
|
escrow_duration:
|
|
type: integer
|
|
maximum: 28800
|
|
minimum: 1800
|
|
default: 10799
|
|
bond_size:
|
|
type: string
|
|
format: decimal
|
|
pattern: ^-?\d{0,2}(?:\.\d{0,2})?$
|
|
default: '3.00'
|
|
latitude:
|
|
type: string
|
|
format: decimal
|
|
pattern: ^-?\d{0,2}(?:\.\d{0,6})?$
|
|
nullable: true
|
|
longitude:
|
|
type: string
|
|
format: decimal
|
|
pattern: ^-?\d{0,3}(?:\.\d{0,6})?$
|
|
nullable: true
|
|
required:
|
|
- currency
|
|
- type
|
|
NoticeSeverityEnum:
|
|
enum:
|
|
- none
|
|
- warning
|
|
- success
|
|
- error
|
|
- info
|
|
type: string
|
|
description: |-
|
|
* `none` - none
|
|
* `warning` - warning
|
|
* `success` - success
|
|
* `error` - error
|
|
* `info` - info
|
|
NullEnum:
|
|
enum:
|
|
- null
|
|
OrderDetail:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
readOnly: true
|
|
status:
|
|
allOf:
|
|
- $ref: '#/components/schemas/StatusEnum'
|
|
default: 0
|
|
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
|
|
default: false
|
|
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
|
|
maxLength: 70
|
|
is_explicit:
|
|
type: boolean
|
|
default: false
|
|
premium:
|
|
type: string
|
|
description: Premium over the CEX price set by the maker
|
|
premium_now:
|
|
type: number
|
|
format: double
|
|
description: Premium over the CEX price at the current time
|
|
satoshis:
|
|
type: integer
|
|
maximum: 5000000
|
|
minimum: 20000
|
|
nullable: true
|
|
satoshis_now:
|
|
type: integer
|
|
description: Maximum size of the order right now in Satoshis
|
|
maker:
|
|
type: integer
|
|
nullable: true
|
|
taker:
|
|
type: integer
|
|
nullable: true
|
|
escrow_duration:
|
|
type: integer
|
|
maximum: 28800
|
|
minimum: 1800
|
|
default: 10799
|
|
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: 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
|
|
price_now:
|
|
type: number
|
|
format: double
|
|
description: Price of the order in the order's currency at the time of request
|
|
(upto 5 significant digits)
|
|
premium_percentile:
|
|
type: number
|
|
format: double
|
|
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
|
|
maker_hash_id:
|
|
type: string
|
|
description: The maker's robot hash
|
|
taker_nick:
|
|
type: string
|
|
description: The taker's robot hash
|
|
taker_hash_id:
|
|
type: string
|
|
description: The taker's robot hash
|
|
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 Nickname
|
|
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: number
|
|
format: double
|
|
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
|
|
minimum: 597.6
|
|
default: 86399
|
|
bond_size:
|
|
type: string
|
|
format: decimal
|
|
pattern: ^-?\d{0,2}(?:\.\d{0,2})?$
|
|
default: '3.00'
|
|
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`
|
|
latitude:
|
|
type: number
|
|
format: double
|
|
description: Latitude of the order for F2F payments
|
|
longitude:
|
|
type: number
|
|
format: double
|
|
description: Longitude of the order for F2F payments
|
|
chat_last_index:
|
|
type: integer
|
|
description: The index of the last message sent in the trade chatroom
|
|
required:
|
|
- expires_at
|
|
- id
|
|
- 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
|
|
default: false
|
|
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
|
|
maxLength: 70
|
|
is_explicit:
|
|
type: boolean
|
|
default: false
|
|
premium:
|
|
type: string
|
|
format: decimal
|
|
pattern: ^-?\d{0,3}(?:\.\d{0,2})?$
|
|
nullable: true
|
|
default: '0.00'
|
|
satoshis:
|
|
type: integer
|
|
maximum: 5000000
|
|
minimum: 20000
|
|
nullable: true
|
|
maker:
|
|
type: integer
|
|
nullable: true
|
|
maker_nick:
|
|
type: string
|
|
maker_hash_id:
|
|
type: string
|
|
maker_status:
|
|
type: string
|
|
description: Status of the nick - "Active", "Seen Recently" or "Inactive"
|
|
price:
|
|
type: number
|
|
format: double
|
|
description: Price in order's fiat currency
|
|
escrow_duration:
|
|
type: integer
|
|
maximum: 28800
|
|
minimum: 1800
|
|
default: 10799
|
|
satoshis_now:
|
|
type: integer
|
|
description: The amount of sats to be traded at the present moment (not
|
|
including the fees)
|
|
bond_size:
|
|
type: string
|
|
format: decimal
|
|
pattern: ^-?\d{0,2}(?:\.\d{0,2})?$
|
|
default: '3.00'
|
|
latitude:
|
|
type: string
|
|
format: decimal
|
|
pattern: ^-?\d{0,2}(?:\.\d{0,6})?$
|
|
nullable: true
|
|
longitude:
|
|
type: string
|
|
format: decimal
|
|
pattern: ^-?\d{0,3}(?:\.\d{0,6})?$
|
|
nullable: true
|
|
required:
|
|
- expires_at
|
|
- id
|
|
- type
|
|
OutMessages:
|
|
type: object
|
|
properties:
|
|
index:
|
|
type: integer
|
|
maximum: 2147483647
|
|
minimum: 0
|
|
time:
|
|
type: string
|
|
format: date-time
|
|
message:
|
|
type: string
|
|
nick:
|
|
type: string
|
|
required:
|
|
- message
|
|
- nick
|
|
- time
|
|
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
|
|
routing_budget_sats:
|
|
type: number
|
|
format: double
|
|
description: The budget allocated for routing costs in Satoshis
|
|
contract_exchange_rate:
|
|
type: number
|
|
format: double
|
|
description: The exchange rate applied to this contract. Taken from externals
|
|
APIs exactly when the taker bond was locked.
|
|
PostMessage:
|
|
type: object
|
|
properties:
|
|
PGP_message:
|
|
type: string
|
|
description: A new chat message
|
|
order_id:
|
|
type: integer
|
|
minimum: 0
|
|
description: Your peer's public key
|
|
offset:
|
|
type: integer
|
|
minimum: 0
|
|
nullable: true
|
|
description: Offset for message index to get as response
|
|
required:
|
|
- PGP_message
|
|
- order_id
|
|
RatingEnum:
|
|
enum:
|
|
- '1'
|
|
- '2'
|
|
- '3'
|
|
- '4'
|
|
- '5'
|
|
type: string
|
|
description: |-
|
|
* `1` - 1
|
|
* `2` - 2
|
|
* `3` - 3
|
|
* `4` - 4
|
|
* `5` - 5
|
|
StatusEnum:
|
|
enum:
|
|
- 0
|
|
- 1
|
|
- 2
|
|
- 3
|
|
- 4
|
|
- 5
|
|
- 6
|
|
- 7
|
|
- 8
|
|
- 9
|
|
- 10
|
|
- 11
|
|
- 12
|
|
- 13
|
|
- 14
|
|
- 15
|
|
- 16
|
|
- 17
|
|
- 18
|
|
type: integer
|
|
description: |-
|
|
* `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` - Successful trade
|
|
* `15` - Failed lightning network routing
|
|
* `16` - Wait for dispute resolution
|
|
* `17` - Maker lost dispute
|
|
* `18` - Taker lost dispute
|
|
Stealth:
|
|
type: object
|
|
properties:
|
|
wantsStealth:
|
|
type: boolean
|
|
required:
|
|
- wantsStealth
|
|
Summary:
|
|
type: object
|
|
properties:
|
|
sent_fiat:
|
|
type: number
|
|
format: double
|
|
description: same as `amount` (only for buyer)
|
|
received_fiat:
|
|
type: number
|
|
format: double
|
|
description: same as `amount` (only for seller)
|
|
sent_sats:
|
|
type: integer
|
|
description: The total sats you sent (only for seller)
|
|
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)
|
|
is_buyer:
|
|
type: boolean
|
|
description: True if the robot is the order 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`
|
|
bond_size_sats:
|
|
type: integer
|
|
description: The amount of Satoshis at stake
|
|
bond_size_percent:
|
|
type: number
|
|
format: double
|
|
description: The relative size of Satoshis at stake
|
|
trade_fee_sats:
|
|
type: integer
|
|
description: Exchange fees in sats (does not include swap fee and miner
|
|
fee)
|
|
trade_fee_percent:
|
|
type: number
|
|
format: double
|
|
description: Exchange fees in percent (does not include swap fee and miner
|
|
fee)
|
|
payment_hash:
|
|
type: string
|
|
description: The payment_hash of the payout invoice
|
|
preimage:
|
|
type: string
|
|
description: The preimage of the payout invoice (proof of payment)
|
|
address:
|
|
type: string
|
|
description: The address of the payout if on-the-fly swap was selected
|
|
txid:
|
|
type: string
|
|
description: The transaction hash of the payout if on-the-fly swap was selected
|
|
Tick:
|
|
type: object
|
|
properties:
|
|
timestamp:
|
|
type: string
|
|
format: date-time
|
|
currency:
|
|
type: integer
|
|
nullable: 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
|
|
default: '0.0000'
|
|
TypeEnum:
|
|
enum:
|
|
- 0
|
|
- 1
|
|
type: integer
|
|
description: |-
|
|
* `0` - BUY
|
|
* `1` - SELL
|
|
UpdateOrder:
|
|
type: object
|
|
properties:
|
|
invoice:
|
|
type: string
|
|
nullable: true
|
|
description: |+
|
|
Invoice used for payouts. Must be PGP signed with the robot's public key. The expected Armored PGP header is -----BEGIN PGP SIGNED MESSAGE-----
|
|
Hash: SHA512
|
|
|
|
maxLength: 15000
|
|
routing_budget_ppm:
|
|
type: integer
|
|
maximum: 100001
|
|
minimum: 0
|
|
nullable: true
|
|
default: 0
|
|
description: Max budget to allocate for routing in PPM
|
|
address:
|
|
type: string
|
|
nullable: true
|
|
description: |+
|
|
Onchain address used for payouts. Must be PGP signed with the robot's public key. The expected Armored PGP header is -----BEGIN PGP SIGNED MESSAGE-----
|
|
Hash: SHA512
|
|
|
|
maxLength: 15000
|
|
statement:
|
|
type: string
|
|
nullable: true
|
|
maxLength: 500000
|
|
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
|
|
Version:
|
|
type: object
|
|
properties:
|
|
major:
|
|
type: integer
|
|
minor:
|
|
type: integer
|
|
patch:
|
|
type: integer
|
|
required:
|
|
- major
|
|
- minor
|
|
- patch
|
|
securitySchemes:
|
|
tokenAuth:
|
|
type: apiKey
|
|
in: header
|
|
name: Authorization
|
|
description: Token-based authentication with required prefix "Token"
|