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
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/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:
- :
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:
- :
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:
- :
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
```
and it's private key can be exported in ascii armored format with:
```shell
gpg --export-secret-keys --armor
```
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_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"