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
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`
description:Premium over the CEX price at the current time
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
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
taker_status:
type:boolean
description:Trueif you are either a taker or maker, False otherwise
price_now:
type:integer
description:Price of the order in the order's currency at the time of request
(upto 5 significant digits)
premium_percentile:
type:integer
description:(Only if `is_maker`) Premium percentile of your order compared
to other public orders in the same currency currently in the order book
num_similar_orders:
type:integer
description:(Only if `is_maker`) The number of public orders of the same
currency currently in the order book
tg_enabled:
type:boolean
description:(Only if `is_maker`) Whether Telegram notification is enabled
or not
tg_token:
type:string
description:(Only if `is_maker`) Your telegram bot token required to enable
notifications.
tg_bot_name:
type:string
description:(Only if `is_maker`) The Telegram username of the bot
is_buyer:
type:boolean
description:Whether you are a buyer of sats (you will be receiving sats)
is_seller:
type:boolean
description:Whether you are a seller of sats or not (you will be sending
sats)
maker_nick:
type:string
description:Nickname (Robot name) of the maker
taker_nick:
type:string
description:Nickname (Robot name) of the taker
status_message:
type:string
description:The current status of the order corresponding to the `status`
is_fiat_sent:
type:boolean
description:Whether or not the fiat amount is sent by the buyer
is_disputed:
type:boolean
description:Whether or not the counterparty raised a dispute
ur_nick:
type:string
description:Your Nick
maker_locked:
type:boolean
description:Trueif maker bond is locked, False otherwise
taker_locked:
type:boolean
description:Trueif taker bond is locked, False otherwise
escrow_locked:
type:boolean
description:Trueif escrow is locked, False otherwise. Escrow is the sats
to be sold, held by Robosats until the trade is finised.
trade_satoshis:
type:integer
description:'Seller sees the amount of sats they need to send. Buyer sees
the amount of sats they will receive '
bond_invoice:
type:string
description:When `status` = `0`, `3`. Bond invoice to be paid
bond_satoshis:
type:integer
description:The bond amount in satoshis
escrow_invoice:
type:string
description:For the seller, the escrow invoice to be held by RoboSats
escrow_satoshis:
type:integer
description:The escrow amount in satoshis
invoice_amount:
type:integer
description:The amount in sats the buyer needs to submit an invoice of
to receive the trade amount
swap_allowed:
type:boolean
description:Whether on-chain swap is allowed
swap_failure_reason:
type:string
description:Reason for why on-chain swap is not available
suggested_mining_fee_rate:
type:integer
description:fee in sats/vbyte for the on-chain swap
swap_fee_rate:
type:number
format:double
description:in percentage, the swap fee rate the platform charges
pending_cancel:
type:boolean
description:Your counterparty requested for a collaborative cancel when
`status` is either `8`, `9` or `10`
asked_for_cancel:
type:boolean
description:You requested for a collaborative cancel `status` is either
`8`, `9` or `10`
statement_submitted:
type:boolean
description:Trueif 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
1sec
failure_reason:
type:string
description:The reason the payout failed
invoice_expired:
type:boolean
description:Trueif 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
bond_size:
type:string
format:decimal
pattern:^-?\d{0,2}(?:\.\d{0,2})?$
trade_fee_percent:
type:integer
description:The fee for the trade (fees differ for maker and taker)
bond_size_sats:
type:integer
description:The size of the bond in sats
bond_size_percent:
type:integer
description:same as `bond_size`
maker_summary:
$ref:'#/components/schemas/Summary'
taker_summary:
$ref:'#/components/schemas/Summary'
platform_summary:
$ref:'#/components/schemas/PlatformSummary'
expiry_reason:
nullable:true
minimum:0
maximum:32767
oneOf:
- $ref:'#/components/schemas/ExpiryReasonEnum'
- $ref:'#/components/schemas/NullEnum'
expiry_message:
type:string
description:The reason the order expired (message associated with the `expiry_reason`)
num_satoshis:
type:integer
description:only if status = `14` (Successful Trade) and is_buyer = `true`
sent_satoshis:
type:integer
description:only if status = `14` (Successful Trade) and is_buyer = `true`
txid:
type:string
description:Transaction id of the on-chain swap payout. Only if status
= `14` (Successful Trade) and is_buyer = `true`
network:
type:string
description:The network eg. 'testnet', 'mainnet'. Only if status = `14`
(Successful Trade) and is_buyer = `true`
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
required:
- expires_at
- id
- platform_summary
- type
OrderPublic:
type:object
properties:
id:
type:integer
readOnly:true
created_at:
type:string
format:date-time
expires_at:
type:string
format:date-time
type:
allOf:
- $ref:'#/components/schemas/TypeEnum'
minimum:0
maximum:32767
currency:
type:integer
nullable:true
amount:
type:string
format:decimal
pattern:^-?\d{0,10}(?:\.\d{0,8})?$
nullable:true
has_range:
type:boolean
min_amount:
type:string
format:decimal
pattern:^-?\d{0,10}(?:\.\d{0,8})?$
nullable:true
max_amount:
type:string
format:decimal
pattern:^-?\d{0,10}(?:\.\d{0,8})?$
nullable:true
payment_method:
type:string
maxLength:70
is_explicit:
type:boolean
premium:
type:string
format:decimal
pattern:^-?\d{0,3}(?:\.\d{0,2})?$
nullable:true
satoshis:
type:integer
maximum: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-----
