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.
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:
- ''
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
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
- network
- node_alias
- node_id
- notice_message
- notice_severity
- num_public_buy_orders
- num_public_sell_orders
- robosats_running_commit_hash
- taker_fee
- version
ListOrder:
type:object
properties:
id:
type:integer
readOnly:true
status:
allOf:
- $ref:'#/components/schemas/StatusEnum'
minimum:0
maximum:32767
created_at:
type:string
format:date-time
expires_at:
type:string
format:date-time
type:
allOf:
- $ref:'#/components/schemas/TypeEnum'
minimum:0
maximum:32767
currency:
type:integer
nullable:true
amount:
type:string
format:decimal
pattern:^-?\d{0,10}(?:\.\d{0,8})?$
nullable:true
has_range:
type:boolean
min_amount:
type:string
format:decimal
pattern:^-?\d{0,10}(?:\.\d{0,8})?$
nullable:true
max_amount:
type:string
format:decimal
pattern:^-?\d{0,10}(?:\.\d{0,8})?$
nullable:true
payment_method:
type:string
maxLength:70
is_explicit:
type:boolean
premium:
type:string
format:decimal
pattern:^-?\d{0,3}(?:\.\d{0,2})?$
nullable:true
satoshis:
type:integer
maximum:5000000
minimum:20000
nullable:true
maker:
type:integer
nullable:true
taker:
type:integer
nullable:true
escrow_duration:
type:integer
maximum:28800
minimum:1800
bond_size:
type:string
format:decimal
pattern:^-?\d{0,2}(?:\.\d{0,2})?$
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
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
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
taker_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
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
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
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"
