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`.
tags:
- chat
security:
- tokenAuth:[]
responses:
'200':
content:
application/json:
schema:
$ref:'#/components/schemas/PostMessage'
description:''
post:
operationId:chat_create
description:Adds one new message to the chatroom.
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/PostMessage'
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:integer
description:Total Volume traded on that particular date
num_contracts:
type:number
description:Number of successful trades on that particular
date
examples:
TruncatedExample:
value:
- <date>:
code:USD
price:'42069.69'
min_amount:'4.2'
max_amount:'420.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
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
satoshis:
type:integer
maximum:5000000
minimum:20000
nullable:true
public_duration:
type:integer
maximum:86400
minimum:597.6
escrow_duration:
type:integer
maximum:28800
minimum:1800
bond_size:
type:string
format:decimal
pattern:^-?\d{0,2}(?:\.\d{0,2})?$
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
Nested:
type:object
properties:
id:
type:integer
readOnly:true
currency:
allOf:
- $ref:'#/components/schemas/CurrencyEnum'
minimum:0
maximum:32767
exchange_rate:
type:string
format:decimal
pattern:^-?\d{0,14}(?:\.\d{0,4})?$
nullable:true
timestamp:
type:string
format:date-time
required:
- currency
- id
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'
minimum:0
maximum:32767
created_at:
type:string
format:date-time
expires_at:
type:string
format:date-time
type:
allOf:
- $ref:'#/components/schemas/TypeEnum'
minimum:0
maximum:32767
currency:
type:integer
nullable:true
amount:
type:string
format:decimal
pattern:^-?\d{0,10}(?:\.\d{0,8})?$
nullable:true
has_range:
type:boolean
min_amount:
type:string
format:decimal
pattern:^-?\d{0,10}(?:\.\d{0,8})?$
nullable:true
max_amount:
type:string
format:decimal
pattern:^-?\d{0,10}(?:\.\d{0,8})?$
nullable:true
payment_method:
type:string
maxLength:70
is_explicit:
type:boolean
premium:
type:string
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
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:Trueif you are either a taker or maker, False otherwise
maker_status:
type:string
description:|-
Status of the maker:
- **'Active'**(seen within last 2 min)
- **'SeenRecently'** (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
description:Longitude of the order for F2F payments
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
min_amount:
type:string
format:decimal
pattern:^-?\d{0,10}(?:\.\d{0,8})?$
nullable:true
max_amount:
type:string
format:decimal
pattern:^-?\d{0,10}(?:\.\d{0,8})?$
nullable:true
payment_method:
type:string
maxLength:70
is_explicit:
type:boolean
premium:
type:string
format:decimal
pattern:^-?\d{0,3}(?:\.\d{0,2})?$
nullable:true
satoshis:
type:integer
maximum:5000000
minimum:20000
nullable:true
maker:
type:integer
nullable:true
maker_nick:
type:string
maker_status:
type:string
description:Status of the nick - "Active" or "Inactive"
price:
type:number
format:double
description:Price in order's fiat currency
escrow_duration:
type:integer
maximum:28800
minimum:1800
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})?$
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
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
PostMessage:
type:object
properties:
PGP_message:
type:string
nullable:true
maxLength:5000
order_id:
type:integer
minimum:0
description:Order ID of chatroom
offset:
type:integer
minimum:0
nullable:true
description:Offset for message index to get as response
required:
- 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` - Sucessful 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:integer
description:same as `amount` (only for buyer)
received_sats:
type:integer
description:same as `trade_satoshis` (only for buyer)
is_swap:
type:boolean
description:Trueif the payout was on-chain (only for buyer)
received_onchain_sats:
type:integer
description:The on-chain sats received (only for buyer and if `is_swap`
is `true`)
mining_fee_sats:
type:integer
description:Mining fees paid in satoshis (only for buyer and if `is_swap`
is `true`)
swap_fee_sats:
type:integer
description:Exchange swap fee in sats (i.e excluding miner fees) (only
for buyer and if `is_swap` is `true`)
swap_fee_percent:
type:number
format:double
description:same as `swap_fee_rate` (only for buyer and if `is_swap` is
`true`
sent_sats:
type:integer
description:The total sats you sent (only for seller)
received_fiat:
type:integer
description:same as `amount` (only for seller)
trade_fee_sats:
type:integer
description:Exchange fees in sats (Does not include swap fee and miner
fee)
Tick:
type:object
properties:
timestamp:
type:string
format:date-time
currency:
allOf:
- $ref:'#/components/schemas/Nested'
readOnly:true
volume:
type:string
format:decimal
nullable:true
price:
type:string
format:decimal
pattern:^-?\d{0,14}(?:\.\d{0,2})?$
nullable:true
premium:
type:string
format:decimal
pattern:^-?\d{0,3}(?:\.\d{0,2})?$
nullable:true
fee:
type:string
format:decimal
required:
- currency
TypeEnum:
enum:
- 0
- 1
type:integer
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"
