Faast SWAP API
-
Current Version: 0.20.1
-
For changes, see History
This document describes the Faast REST-like API to be used to easily convert between any cryptocurrency.
Introduction ¶
Overview
The goal of the Faast API is to provide an instant, and secure method to convert from one cryptocurrency to another. To achieve this, a user specifies which currency they possess (deposit currency), and which currency they would like to obtain (withdrawal currency), as well as a wallet address for the currency they would like to obtain.
The Faast API then generates a unique deposit wallet address for the “deposit currency”, where the user can send any arbitrary amount of cryptocurrency. Upon noticing any transaction on this deposit address Faast will immediately fullfill an order at the current market rate, and send an equivalent amount of “withdrawal currency” to the users specified “wallet address”.
Faast never takes custody of users cryptocurrency, and has no user account system. It is designed for instant, safe, and secure conversion in between any arbitrary set of cryptocurrencies.
Basic flow
-
Get a current price (varies in real time with market)
-
Generate a swap and deposit address
-
Send cryptocurrency to the deposit address
-
Monitor the status for completion
Fixed pricing vs Variable Pricing ¶
Faast provides two forms of pricing: fixed and variable. When using fixed pricing, an order is created expecting a specific deposit amount in return for a specific withdrawal amount. When using variable pricing, any arbitrary amount can be deposited, and an equivalent withdrawal amount will be calculated using the prevailing exchange rate at the time the deposit is received. This model provides optimal user experience, as well as developer flexibility.
Fixed Pricing
The Faast API is inherently asynchronous. There will always be a time lag in-between the time that a swap is created, and a deposit is sent for that specific swap. Given the volatility of cryptocurrency markets, even these short delays can cause pricing discrepancies, and as a result, poor user experience.
For this reason, Faast provides a “fixed pricing” option when creating a swap. Faast will guarantee the price quoted back in the response assuming the deposit is received before the expiry period. To provide the best experience with fixed pricing, timing is paramount.
How to create a fixed price swap
When calling the /swap
endpoint, ensure a deposit_amount
is specified, and the generated swap will return a price based on the market depth at the time of the request. The response will contain a price
and price_locked_until
parameters.
A deposit from the customer must be received before price_locked_until
, and match the deposit_amount
expected to ensure the price will honored. In the off chance that signing a transaction takes longer than expected, the /swaps/refresh
endpoint can be called to refresh the price and re-quote based on an updated market rate.
All transactions are considered “received” when they are detected by a blockchain node on the Faast network. Transactions do not need to be “confirmed” or in a “block” to be considered “received”.
Variable Pricing
Variable pricing allows for more flexibility, in that users can deposit any amount and receive an equivalent payout based on the prevailing rate at the time the deposit is received.
Given that the API does not know the exact deposit amount, it is impossible to accurately estimate the price of the swap beforehand (due to market depth issues on most cryptocurrencies). For this reason, the specific price of the swap will be quoted when a deposit is received by one of the blockchain nodes on the Faast network.
To create a variable price swap, simply omit the deposit_amount
when calling the /swap
endpoint.
Minimums and Maximums
Minimum and maximum deposit amounts are returned in the pricing APIs. Cryptocurrency sent to the deposit address cannot be processed if it is below the minimum. Deposits that exceed the maximum value may be processed or refunded depending on various factors.
Affiliate Program ¶
Question: Why should I integrate with the Faast API and not XYZ API?
Answer: Faast provides the best opportunity for revenue generation as an API integrator.
Earn revenue today by integrating the Faast swap API into your product or service! No sign up is required, and payouts are instant!
Faast allows API integrators to quickly and easily earn revenue by setting a specific percentage of each swap they would like to earn as a commission. Contrary to competitive implementations, the Faast affiliate program allows the developer to choose the exact commission they would like to earn.
Withdrawals of earnings can be initiated via the API or via the Faast Affiliate Portal.
How it works:
When generating a swap on behalf of a customer, simply add the affiliate_margin
and affiliate_id
fields to the request API.
Then, when the customer deposits funds for the swap, the following will happen:
- The
price
the customer is quoted will be adjusted down byaffiliate_margin
- An equivalent amount of Bitcoin (
deposit_amount * affiliate_margin
) will be withheld for an affiliate payout - The customer will receive their
withdrawal_currency
payout - After the total affiliate payout for a specific
affiliate_id
reaches 0.01BTC, it can be withdrawn via an API request or via the aforementioned portal.
Affiliate margin
The affiliate margin is a percentage (from 0.01
to 5
) an affiliate would like to charge its customers. Faast prices its swaps based on the prevailing rates on the market, plus an approximate 1.0%
fee. Affiliate margins are applied on-top of Faast’s native fee.
It is suggested that affiliates make clear to their users the affiliate margin being applied to a swap. The recommended margin is 0.5%
, but affiliates are welcome to vary this rate based on business opportunities and application.
Geographic Restrictions ¶
The Faast API provides services to properly restrict certain functions based on a customers location, similar to the faa.st website. There are effectively three classes of customers.
-
Blocked customers - These customers should not be permitted to access any Faast service.
-
Restricted customers - These customers should not be permitted to access tokens listed as “restricted”.
-
Unrestricted customers - These customers can access all Faast services
Faast provides two API’s to assist with geo-restriction. The first API performs a lookup to identify if a customer is blocked/restricted. The second API classifies if assets are restricted or not.
Geo restrict implementation guidelines
API Integrators who offer Faast services to end customers should follow these steps to ensure compliance with the Faast terms and conditions:
-
Query the customers restrictions using the geoIP endpoint
-
If
blocked: true
deny this customer all services -
If
restricted: true
deny customers access to tokens listed asrestricted: true
in the asset list
Alternatively, the end customer’s IP address may be provided as user_ip_address
during swap creation. When this field is provided, georestriction will be determined using that address.
If you have any questions at all about these requirements, feel free to reach out to [email protected] for clarification.
Integration Testing ¶
Faast provides a staging server that can be used for integration testing. It provides the same API, but with the following differences:
-
It uses the TestNet bitcoin and ethereum (ropsten) test network, and thus expects testnet addresses and coins (eg. mqdofsXHpePPGBFXuwwypAqCcXi48Xhb2f)
-
ERC20 Tokens are all a single custom Faast Token on ropsten address: 0xe72bbed5cf09686c62ed5be8f571a7670c11c468
-
testnet coins may or may not be sent to the testnet address provided, depending on how our staging servers are configured
The testing base url is https://testapi.faa.st
Authentication ¶
The majority of the Faast APIs have no authentication requirement. The /affiliate APIs are the exception to this, for privacy reasons. Authentication is accomplished through the use of a shared affiliate ID and secret, used to sign requests. An affiliate ID and secret can be obtained through the /affiliate/register API.
Each request must provide the following headers:
-
affiliate-id - affiliate ID provided by you
-
nonce - an integer value appended to the body when generating the HMAC
-
signature - output of the HMAC algorithm
Node.js example:
const requestData = {...}
const requestJSON = JSON.stringify(requestData)
const nonce = String(Date.now())
const signature = crypto
.createHmac('sha256', 'secret')
.update(nonce + requestJSON)
.digest('hex')
request.post({
url: 'https://testapi.faa.st',
headers: {
'affiliate-id': AFFILIATE_ID,
nonce: nonce,
signature: signature
},
json: requestData
}, function(err, res, body) { ... }
Base URL ¶
Production
The production base URL is https://api.faa.st
Test
The test base URL is https://testapi.faa.st
Swap Requests ¶
Swap statuses
-
awaiting deposit
- initial state after a swap has been created -
awaiting network confirmation
- waiting for confirmations of the deposit -
received
- deposit has been processed -
withdrawing
- withdrawal is being sent -
complete
- swap has completed -
cancelled
- no deposit was found -
refunding
- deposit will be refunded to the supplied refund address -
refunded
- deposit was refunded to the supplied refund address
The normal flow for a swap is through the first five statuses in that order. A swap may be cancelled if no valid deposit is seen after a reasonable time period, but note that if a deposit does arrive at the address later on, it will be re-priced and processed.
Create ¶
CreatePOST/api/v2/public/swap
Create a new swap order, and generate a deposit address. Note that the deposit_address field may be accompanied by a deposit_address_extra_id field for certain currencies, which must be used to ensure the deposit is recognized.
Example URI
Headers
Content-Type: application/json
Body
{
"user_id": "my_user_id_992", (optional, user provided ID to be used for historical order lookups)
"user_ip_address": "67.195.197.23", (optional, IP address of end-user for georestriction purposes)
"deposit_amount": 0.02, (optional, specify amount for a fixed price swap)
"deposit_currency": "ETH",
"withdrawal_address": "0xf9357f4fdef81103ed55296649a7cacf04e80ef3",
"withdrawal_address_extra_id": "11", (only required for certain currencies)
"withdrawal_amount": 50, (optional, specify amount for a fixed price swap)
"deposit_currency": "ETH",
"withdrawal_currency": "BAT",
"refund_address": "0xf9357f4fdef81103ed55296649a7cacf04e80ef3", (optional, address to send a refund if there are any issues)
"refund_address_extra_id": "14", (only required for certain currencies)
"affiliate_margin": 5, (optional, percentage fee, decimal from 0.0 to 5.0)
"affiliate_fixed_fee": 1, (optional, fixed USD amount (eg $1), decimal from 0.0 to 5.0)
"affiliate_id": "my_affiliate_id", (optional, registered affiliate ID)
"price_quote_id": "1595965456677", (optional, ID of a quoted price returned from the pricing APIs)
}
200
Headers
Content-Type: application/json; charset=utf-8
Body
{
"swap_id": "30711734-e4ee-4ff1-a45b-4020cef8488b",
"user_id": "my_user_id_992",
"created_at": "2018-08-17T18:08:59.004Z",
"deposit_address": "0x94fa1b52E7B6282dad0213e17A8BF7B2538b4b1E",
"deposit_address_extra_id": "10",
"deposit_amount": 0.02,
"deposit_currency": "ETH",
"spot_price": 0.03399216,
"price": 0.035870226,
"price_locked_at": "2018-08-17T18:08:58.829Z",
"price_locked_until": "2018-08-17T18:23:58.829Z",
"price_quote_id": "1595965456677",
"withdrawal_amount": 0.557565486,
"withdrawal_address": "0x3d6Bb40C0dDe451812A935163cC57974063b8dA3",
"withdrawal_address_extra_id": "11",
"withdrawal_currency": "BNB"
}
Fetch ¶
FetchGET/api/v2/public/swaps/{swapId}
Get the status of a swap by its ID.
Example URI
- swapId
string
(required) Example: 3f1c1a39...swap_id from Create swap response
Headers
Content-Type: application/json
200
Headers
Content-Type: application/json; charset=utf-8
Body
{
"swap_id": "3f1c1a39-de8f-457d-ae2f-11383acd9403",
"created_at": "2018-08-16T20:04:48.950Z",
"updated_at": "2018-08-17T22:14:54.620Z",
"user_id": "my_user_id_992",
"deposit_address": "0x94fa1b52E7B6282dad0213e17A8BF7B2538b4b1E",
"deposit_address_extra_id": "10",
"deposit_amount": 0.02,
"deposit_currency": "ETH",
"spot_price": 0.03375493,
"price": 0.03731607000000001,
"price_locked_at": "2018-08-17T22:14:54.619Z",
"price_locked_until": "2018-08-17T22:29:54.619Z",
"withdrawal_address": "0x3d6Bb40C0dDe451812A935163cC57974063b8dA3",
"withdrawal_address_extra_id": "11",
"withdrawal_amount": 0.53596212,
"withdrawal_currency": "BNB",
"refund_address": null,
"status": "awaiting deposit"
}
Fetch/Refresh ¶
Fetch/RefreshPOST/api/v2/public/swaps/{swapId}/refresh
Re-price a swap if the previously established price has expired.
Example URI
- swapId
string
(required) Example: 3f1c1a39...swap_id from Create swap response
Headers
Content-Type: application/json
200
Headers
Content-Type: application/json; charset=utf-8
Body
{
"swap_id": "3f1c1a39-de8f-457d-ae2f-11383acd9403",
"created_at": "2018-08-16T20:04:48.950Z",
"updated_at": "2018-08-17T22:14:54.620Z",
"user_id": "my_user_id_992",
"deposit_address": "0x94fa1b52E7B6282dad0213e17A8BF7B2538b4b1E",
"deposit_address_extra_id": "10",
"deposit_amount": 0.02,
"deposit_currency": "ETH",
"spot_price": 0.03375493,
"price": 0.03731607000000001,
"price_locked_at": "2018-08-17T22:14:54.619Z",
"price_locked_until": "2018-08-17T22:29:54.619Z",
"withdrawal_address": "0x3d6Bb40C0dDe451812A935163cC57974063b8dA3",
"withdrawal_address_extra_id": "11",
"withdrawal_amount": 0.53596212,
"withdrawal_currency": "BNB",
"refund_address": null,
"status": "awaiting deposit"
}
Provide Deposit Info ¶
Provide Deposit InfoPOST/api/v2/public/swaps/{swapId}/deposit
Save the deposit transaction hash into the swap record. It will be provided in the response as deposit_tx_id.
Example URI
- swapId
string
(required) Example: 3f1c1a39...swap_id from Create swap response
Headers
Content-Type: application/json
Body
{
"tx_id": "0xasdf..."
}
200
Headers
Content-Type: application/json; charset=utf-8
Body
{
"swap_id": "3f1c1a39-de8f-457d-ae2f-11383acd9403",
"created_at": "2018-08-16T20:04:48.950Z",
"updated_at": "2018-08-17T22:14:54.620Z",
"user_id": "my_user_id_992",
"deposit_address": "0x94fa1b52E7B6282dad0213e17A8BF7B2538b4b1E",
"deposit_address_extra_id": "10",
"deposit_tx_id": "0xasdf...",
"deposit_amount": 0.02,
"deposit_currency": "ETH",
"spot_price": 0.03375493,
"price": 0.03731607000000001,
"price_locked_at": "2018-08-17T22:14:54.619Z",
"price_locked_until": "2018-08-17T22:29:54.619Z",
"withdrawal_address": "0x3d6Bb40C0dDe451812A935163cC57974063b8dA3",
"withdrawal_address_extra_id": "11",
"withdrawal_amount": 0.53596212,
"withdrawal_currency": "BNB",
"refund_address": null,
"status": "awaiting deposit"
}
Query Requests ¶
Get A Price ¶
Get A PriceGET/api/v2/public/price/{pair}{?deposit_amount}{?affiliate_margin}{?affiliate_fixed_fee}{?withdrawal_amount}
This will return a price for a selected currency pair. The “maximum_deposit” returned is the suggested maximum based on pricing factors. The “minimum_deposit” indicates the minimum acceptable deposit – deposits below that amount cannot be processed.
Example URI
- pair
string
(required) Example: BTC_ETHThe pair is
depositCurrency_withdrawalCurrency
- affiliate_margin
string
(optional) Example: 1decimal from 0 to 5 provide affiliate margin to receive a price that includes it
- affiliate_fixed_fee
string
(optional) Example: 1decimal from 0 to 5, the provided fixed fee will be incorporated into the total
withdrawal_fee
returned by this endpoint- deposit_amount
string
(optional) Example: 0.1provide a deposit amount to receive a market-depth price
- withdrawal_amount
string
(optional) Example: 0.1provide a withdrawal amount to receive a market-depth price
Headers
Content-Type: application/json
200
Headers
Content-Type: application/json; charset=utf-8
Body
{
"pair": "BTC_ETH",
"price": 0.01754196,
"deposit_amount": 0.35,
"withdrawal_fee": 0.00558457, // Faast fixed fee + affiliate fixed fee, in withdrawal_currency
"minimum_deposit": 0.00063935,
"maximum_deposit": 0.96873316,
"minimum_withdrawal": 0.03645336,
"maximum_withdrawal": 55.8476398,
"terms": "https://faa.st/terms"
}
Get Supported Currencies ¶
Get Supported CurrenciesGET/api/v2/public/currencies
This will return a list of supported cryptocurrencies on Faast. Make close note of the returned deposit
and receive
fields. deposit
indicates if swaps can be created with the currency as the deposit_currency
. receive
indicates if the specific currency can be set as the withdrawal_currency
in a swap. Restricted indicates if the token should be restricted from use based on geographic restrictions.
Example URI
Headers
Content-Type: application/json
200
Headers
Content-Type: application/json; charset=utf-8
Body
[
{
"name": "Bitcoin",
"symbol": "BTC",
"walletUrl": "https://copay.io",
"deposit": true,
"receive": true,
"infoUrl": "https://bitcoin.org",
"decimals": 8,
"cmcID": "bitcoin",
"iconUrl": "https://api.faa.st/api/v1/public/static/img/coins/icon_BTC.png",
"restricted": false - If this currency is restricted
},
{
"name": "Ethereum",
"symbol": "ETH",
"walletUrl": "https://faa.st",
"deposit": true,
"receive": true,
"infoUrl": "https://ethereum.org",
"decimals": 18,
"cmcID": "ethereum",
"iconUrl": "https://api.faa.st/api/v1/public/static/img/coins/icon_ETH.png",
"restricted": false - If this currency is restricted
},
{
"name": "Augur",
"validate": "ETH",
"symbol": "REP",
"walletUrl": "https://faa.st",
"deposit": true,
"receive": true,
"ERC20": true,
"infoUrl": "https://etherscan.io/token/0x1985365e9f78359a9B6AD760e32412f4a445E862",
"contractAddress": "0x1985365e9f78359a9B6AD760e32412f4a445E862",
"decimals": 18,
"cmcID": "augur",
"iconUrl": "https://api.faa.st/api/v1/public/static/img/coins/icon_REP.png",
"restricted": false - If this currency is restricted
}, ...
]
Get A Supported Currency ¶
Get A Supported CurrencyGET/api/v2/public/currencies/{currency}
This will return info about a given supported currency.
Example URI
- currency
string
(required) Example: BTCcurrency to retrieve info for
Headers
Content-Type: application/json
200
Headers
Content-Type: application/json; charset=utf-8
Body
{
"name": "Bitcoin",
"symbol": "BTC",
"walletUrl": "https://copay.io",
"deposit": true,
"receive": true,
"infoUrl": "https://bitcoin.org",
"decimals": 8,
"cmcID": "bitcoin",
"iconUrl": "https://api.faa.st/api/v1/public/static/img/coins/icon_BTC.png"
"restricted": false - If this currency is restricted
}
Get All Prices ¶
Get All PricesGET/api/v2/public/price/all{?format}{?usd_depths}{?usd_depth}{?affiliate_margin}{?affiliate_fixed_fee}
This will return pricing info for all currencies in either object (“dict”) or “list” format. Suggested maximum deposit and withdrawal amounts are provided per currency.
Note: if usd_depths
is provided, the format of the response will change. See the second Response example.
Example URI
- format
string
(optional) Example: dict“dict” or “list”, default “dict”
- usd_depths
string
(optional) Example: 1000,5000,10000provide a list of USD depths to return market depth prices at those depths
- usd_depth
string
(optional) Example: 1000provide a USD depth to return market depth prices at that USD depth
- affiliate_margin
string
(optional) Example: 1(optional, decimal from 0.0 to 5.0) provide affiliate margin to return prices that include it
- affiliate_fixed_fee
string
(optional) Example: 1decimal from 0 to 5, the provided fixed fee will be incorporated into the total
withdrawal_fees
returned by this endpoint
Headers
Content-Type: application/json
200
Headers
Content-Type: application/json; charset=utf-8
Body
note: standard dict format response (no usd_depths)
{
"minimum_deposits": {
"BAT": 18.67064974,
"BTC": 0.00040536,
"ETH": 0.01457336,
"TUSD": 3.30425588,
"ZRX": 4.60574797
},
"maximum_deposits": {
"BAT": 701821,
"BTC": 100,
"ETH": 1421,
"TUSD": 80881,
"ZRX": 132395
},
"maximum_withdrawals": {
"BAT": 225742,
"BTC": 100,
"ETH": 1792,
"TUSD": 82944,
"ZRX": 58200
},
"withdrawal_fees": {
"BAT": 0,
"BTC": 0,
"ETH": 0,
"TUSD": 0,
"ZRX": 0
},
"prices": {
"BAT": {
"BTC": 37528.00597461,
"ETH": 1288.22461165,
"TUSD": 5.71288835,
"ZRX": 4.10593914
},
"BTC": {
"BAT": 0.000027,
"ETH": 0.03449866,
"TUSD": 0.00015299,
"ZRX": 0.00010996
},
"ETH": {
"BAT": 0.00078709,
"BTC": 29.29245176,
"ETH": 13018.36041509,
"TUSD": 57.73250944,
"ZRX": 41.49322641
},
"TUSD": {
"BAT": 0.17845856,
"BTC": 6641.55432197,
"ETH": 227.98476804,
"ZRX": 0.72665246
},
"ZRX": {
"BAT": 0.24875046,
"BTC": 9257.55342667,
"ETH": 317.78422163,
"TUSD": 1.40927736
}
}
}
200
Headers
Content-Type: application/json; charset=utf-8
Body
note: usd_depths=5000,10000
{
"minimum_deposits": {
"BTC": 0.00040536,
"ETH": 0.01457336,
"TUSD": 3.30425588
},
"maximum_deposits": {
"BTC": 100,
"ETH": 1421,
"TUSD": 80881
},
"maximum_withdrawals": {
"BTC": 100,
"ETH": 1792,
"TUSD": 82944
},
"prices": {
"BTC": {
"ETH": {
"5000": 0.03098423,
"10000": 0.03101745
},
"TUSD": {
"5000": 0.00012096,
"10000": 0.00012143
}
},
"ETH": {
"BTC": {
"5000": 32.71543652,
"10000": 32.72608979
},
"TUSD": {
"5000": 0.0039337,
"10000": 0.00395037
}
},
"TUSD": {
"BTC": {
"5000": 8423.34421837,
"10000": 8424.75504565
},
"ETH": {
"5000": 259.43420062,
"10000": 259.75592296
}
}
}
}
Query Swaps ¶
Query SwapsGET/api/v2/public/swaps{?any_address,user_id,withdrawal_address,withdrawal_address_extra_id,deposit_address,deposit_address_extra_id,refund_address,refund_address_extra_id,page,limit}
Query swaps by withdrawal address or provided User ID. Results are paginated. “total” is the total matching results for the entire query. At least one filtering parameter is required.
Example URI
- any_address
string
(optional) Example: "0x33ec06a42f7d6b4ceca597edaf28ff1580b283df"find swaps for a given address in any address field
- user_id
string
(optional) Example: "presidentofbitcoin"find swaps for a given client-provided user ID
- withdrawal_address
string
(optional) Example: "0x33ec06a42f7d6b4ceca597edaf28ff1580b283df"find swaps for a given withdrawal address
- withdrawal_address_extra_id
string
(optional) Example: "103"applicable for currencies with an extra-id (payment memo, etc)
- deposit_address
string
(optional) Example: "0x33ec06a42f7d6b4ceca597edaf28ff1580b283df"find swaps for a given deposit address
- deposit_address_extra_id
string
(optional) Example: "103"applicable for currencies with an extra-id (payment memo, etc)
- refund_address
string
(optional) Example: "0x33ec06a42f7d6b4ceca597edaf28ff1580b283df"find swaps for a given refund address
- refund_address_extra_id
string
(optional) Example: "103"applicable for currencies with an extra-id (payment memo, etc)
- limit
string
(optional) Example: 10number of results returned per pagination page
- page
string
(optional) Example: 5page number of paginated results to return
Headers
Content-Type: application/json
200
Headers
Content-Type: application/json; charset=utf-8
Body
{
"total": 1,
"orders": [
{
"swap_id": "ab0d3433-723a-4b6e-8c1c-a487103c1eb1",
"user_id": "my_user_id_992",
"created_at": "2018-08-17T16:25:47.659Z",
"updated_at": "2018-08-17T17:01:14.130Z",
"deposit_address": "0x94fa1b52E7B6282dad0213e17A8BF7B2538b4b1E",
"deposit_address_extra_id": "10",
"deposit_amount": 0.02,
"deposit_currency": "ETH",
"spot_price": 0.03435726,
"price": 0.037981955000000005,
"price_locked_at": "2018-08-17T16:25:47.650Z",
"price_locked_until": "2018-08-17T16:40:47.650Z",
"withdrawal_address": "0x3d6Bb40C0dDe451812A935163cC57974063b8dA3",
"withdrawal_address_extra_id": "11",
"withdrawal_currency": "BNB",
"withdrawal_amount": 1.16252102,
"status": "complete",
"amount_deposited": 0.04,
"amount_withdrawn": 1.16252102,
"transaction_id": "0x849cfa8edde231c50cab8a4a3a2a1c8530797c870ef28b189cd5b58d63eb2ac2"
}
]
}
Get GeoRestrict Info ¶
Get GeoRestrict InfoGET/api/v2/public/geoinfo/{ip_address}
This API will return GEO restrict information of a specific IP address. If no ip_address
is provided in the request, the response will be based on the IP address of the requestor.
If making requests from a server on behalf of a client, provide the origin client’s ip address as ip_address
. The response will then be based on the provided IP address.
Use this API to properly implement geographic restrictions.
If blocked: true
, the customer should be denied access to all Faast services.
If restricted: true
, the customer should not be permitted to access any token listed as restricted:true
from the supported currencies list.
Example URI
- ip_address
string
(optional) Example: 196.52.2.25IP address to query. If not provided, origin IP will be used.
Headers
Content-Type: application/json
200
Headers
Content-Type: application/json; charset=utf-8
Body
{
"ip": "196.52.2.25", - IP address that was queried
"blocked": true, - If the customer is blocked from all Faast services
"restricted": true, - If the customer is restricted
"country": "US",
"location_details": {}, - Unstructured data on the customers location
"terms": "https://faa.st/terms"
}
Validate an Address ¶
Validate an AddressPOST/api/v2/public/address
Validates a provided cryptocurrency wallet address and returns its “standardized” representation. Standardization varies depending on the currency, for example returning the mixed-case checksum format of an Ethereum address or converting a legacy Litecoin address to the preferred P2SH version.
In some cases, the API will return true for addresses which are technically valid, but in a format Faast does not accept (eg. a legacy Litecoin address). In this case, the standardized version of the address can be used to create the swap.
Example URI
Headers
Content-Type: application/json
Body
{
"address": "0xc1269f68df40098595292d78eb21ac86af71c60b",
"currency": "BAT"
}
200
Headers
Content-Type: application/json; charset=utf-8
Body
{
"address": "0xc1269f68df40098595292d78eb21ac86af71c60b",
"currency": "BAT",
"valid": true,
"acceptable": true,
"blockchain": "ETH",
"standardized": "0xC1269F68dF40098595292d78EB21ac86Af71C60b",
"terms": "https://faa.st/terms"
}
Affiliate ¶
Register ¶
RegisterPOST/api/v2/public/affiliate/register
Register an affiliate ID. The response will contain a secret which must be used to sign requests (see Authentication section). Note that it is not necessary to register an affiliate ID before it is used in swaps, but that the private /affiliate APIs cannot be accessed until the ID has been registered.
Example URI
Headers
Content-Type: application/json
Body
{
"affiliate_id": "my_affiliate_id", (user provided ID)
"contact_email": "[email protected]" (email address for support outreach)
}
200
Headers
Content-Type: application/json; charset=utf-8
Body
{
"affiliate_id": "my_affiliate_id",
"secret": "2f03aa6c02061447560b9880bc4924ea2435",
"contact_email": "[email protected]"
}
Get Affiliate Stats ¶
Get Affiliate StatsGET/api/v2/public/affiliate/stats{?start,end}
NOTE: This API must be authenticated using an affiliate ID and secret obtained through the /affiliate/register API.
Get statistics related to the registered affiliate address, including total swaps, total value, and affiliate payout totals.
Example URI
- start
restrict stats to period starting at date (msec)
(optional) Example: "1540324997035",- end
restrict stats to period end at date (msec)
(optional) Example: "1540324997036",
Headers
Content-Type: application/json
200
Headers
Content-Type: application/json; charset=utf-8
Body
{
"date": "2018-10-23T16:03:46.743Z",
"address": "mqdofsXHpePPGBFXuwwypAqCcXi48Xhb2f",
"totals": {
"swaps_created": 34,
"swaps_completed": 16,
"value_usd": 0,
"value_btc": 0,
"affiliate_payouts_usd": 0,
"affiliate_payouts_btc": 0,
"by_currency": {
"BNB": {
"swaps_completed": 8,
"value_currency": 0,
"value_usd": 0,
"value_btc": 0,
"affiliate_payouts_usd": 0,
"affiliate_payouts_btc": 0,
"deposits": {
"swaps_completed": 4,
"value_currency": 0,
"value_usd": 0,
"value_btc": 0,
"affiliate_payouts_usd": 0,
"affiliate_payouts_btc": 0
},
"withdrawals": {
"swaps_completed": 4,
"value_currency": 0,
"value_usd": 0,
"value_btc": 0,
"affiliate_payouts_usd": 0,
"affiliate_payouts_btc": 0
}
},
"ETH": {
"swaps_completed": 8,
"value_currency": 0,
"value_usd": 0,
"value_btc": 0,
"affiliate_payouts_usd": 0,
"affiliate_payouts_btc": 0,
"deposits": {
"swaps_completed": 4,
"value_currency": 0,
"value_usd": 0,
"value_btc": 0,
"affiliate_payouts_usd": 0,
"affiliate_payouts_btc": 0
},
"withdrawals": {
"swaps_completed": 4,
"value_currency": 0,
"value_usd": 0,
"value_btc": 0,
"affiliate_payouts_usd": 0,
"affiliate_payouts_btc": 0
}
}
}
},
"terms": "https://faa.st/terms"
}
Withdraw ¶
WithdrawPOST/api/v2/public/affiliate/withdraw
NOTE: This API must be authenticated using an affiliate ID and secret obtained through the /affiliate/register API.
Request an affiliate payment withdrawal to the provided withdrawal_address
.
Example URI
Headers
Content-Type: application/json
Body
{
"withdrawal_address": "mqdofsXHpePPGBFXuwwypAqCcXi48Xhb2f", (Bitcoin address for payment)
}
200
Headers
Content-Type: application/json; charset=utf-8
Body
{
"status": "pending",
}
Query Affiliate Withdrawals ¶
Query Affiliate WithdrawalsGET/api/v2/public/affiliate/withdrawals{?page,limit}
NOTE: This API must be authenticated using an affiliate ID and secret obtained through the /affiliate/register API.
Query affiliate withdrawals for the authenticated affiliate ID.
Example URI
- limit
string
(required) Example: 10number of results returned per pagination page
- page
string
(required) Example: 5page number of paginated results to return
Headers
Content-Type: application/json
200
Headers
Content-Type: application/json; charset=utf-8
Body
{
page: 1,
limit: 1,
total: 18,
withdrawals: [
{
created_at: '2019-01-07T12:14:23.782Z',
updated_at: '2019-01-07T12:38:43.510Z',
affiliate_id: 'my_affiliate_id',
withdrawal_id: 'cd897515-79d5-4fcb-89ec-5fe4b58adc53',
withdrawal_address: '1MsIASoHjqynMaMnP7SCmanyEWiLsTqoU5',
withdrawal_amount: 1.02709828,
withdrawal_currency: 'BTC',
status: 'complete',
transaction_id: '85958bc208952017e01529c91a6701eb01fb515d3f5799f814f061dbb0114bf6'
}
}
Create Affiliate CSV Export Request ¶
Create Affiliate CSV Export RequestGET/api/v2/public/affiliate/swaps/export{?withdrawal_address}{?user_id}{?limit}
NOTE: This API must be authenticated using an affiliate ID and secret obtained through the /affiliate/register API.
Create a CSV export request with the given parameters. A successful response will contain a url
parameter, which is a temporary unauthenticated download link which can be used to retrieve the CSV file.
The fields included in the CSV export are:
"swap_id"
"order_id"
"user_id"
"created_at"
"updated_at"
"processed_at"
"deposit_tx_id"
"deposit_address"
"deposit_address_extra_id"
"deposit_amount"
"deposit_currency"
"spot_price"
"price"
"price_locked_at"
"price_locked_until"
"withdrawal_address"
"withdrawal_address_extra_id"
"withdrawal_amount"
"withdrawal_currency"
"refund_address"
"value_btc"
"value_usd"
"affiliate_payment_amount_dc"
"affiliate_payment_amount_fiat"
Example URI
- withdrawal_address
string
(optional) Example: "0x33ec06a42f7d6b4ceca597edaf28ff1580b283df"export only swaps for a given withdrawal address
- user_id
string
(optional) Example: "presidentofbitcoin"export only swaps for a given client-provided user ID
- limit
string
(required) Example: 10number of results
Headers
Content-Type: application/json
200
Headers
Content-Type: application/json; charset=utf-8
Body
{
"url": "https://api.faa.st/api/v2/public/affiliate/export/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"terms": "https://faa.st/terms"
}
History ¶
Version 0.1:
-
Add currently supported APIs
-
GET rate
-
GET txStat
-
POST shift
-
Add initial list of supported Deposit and withdrawal Currencies
Version 0.2:
-
Removed list of supported currencies from doc, use v1 currencies API to get currency list
-
Removed /shift
-
Removed /txStat
-
Add initial v2 APIs
-
GET price
-
GET swaps
-
POST swap
-
POST swap/refresh
Version 0.2.1:
- Fixed lack of URI parameter in refresh API
Version 0.3.0:
- added GET swap
Version 0.4.0:
- added GET /affiliate/:address/payouts
Version 0.5.0:
-
added GET /price/all
-
added GET /affiliate/:address/stats
-
fixed affiliate payouts documentation to include cursor
Version 0.6.0:
- added POST /swap/deposit
Version 0.7.0:
-
/affiliate/stats and /affiliate/payouts now require authentication
-
added POST /affiliate/register for obtaining api keys
Version 0.8.0:
-
/affiliate/stats response format has changed
-
/affiliate/stats can be restricted by start/end date
Version 0.9.0:
-
/swap: added new fresh_deposit_address parameter
-
added description of swap status values
Version 0.10.0:
- removed affiliate_payment_address and affiliate_margin from swap responses
Version 0.11.0:
- added maximum_deposits and maximum_withdrawals to price/all API
Version 0.12.0:
-
added USD depth to price/all for market depth pricing
-
added affiliate margin to price/all for pricing results that include it
-
added ability to provide withdrawal amount when creating a swap
-
added ability to provide deposit amount, withdrawal amount, and affiliate margin when fetching a price
-
indicate withdrawal amount is returned in swap data when created with a deposit amount
Version 0.13.0:
- Added Geo Restriction details
Version 0.14.0:
-
Affiliate API key is now called ‘Affiliate ID’ and field names have been adjusted to match
-
/affiliate/withdraw added for requesting an affiliate payment withdrawal
-
added maximum_deposit in response to /price
Version 0.14.1:
- Fixed error in authentication documentation – nonce comes before body
Version 0.15.0:
-
Fixed error in order of status transitions in status section
-
Documented affiliate CSV export endpoints
Version 0.15.1:
- Added new “withdrawing” and “refunding” status descriptions
Version 0.16.0:
-
Added new “usd_depths” query parameter to all prices endpoint
-
Added user_ip_address body parameter to swap creation endpoint
Version 0.17.0:
-
Added /address endpoint for address validation and standardization
-
Numerous cleanups and clarifications
Version 0.17.1:
- Added ‘acceptable’ to /address endpoint to indicate whether Faast will accept the address as-is
Version 0.18.0:
-
Added ‘withdrawal_address_extra_id’ to support withdrawing currencies which require an extra address identifier
-
Added ‘deposit_address_extra_id’ to support depositing currencies which require an extra address identifier
Version 0.19.0:
-
Added affiliate fixed fee to pricing and swap creation endpoints
-
Added withdrawal fee to pricing endpoints
-
Added min and max withdrawal amounts to pricing endpoints
-
Added refund address extra ID for currencies requiring it
Version 0.19.1:
- Added docs for affiliate withdrawals endpoint
Version 0.19.2:
- Added query swaps by deposit address and extra-id fields
Version 0.19.3:
-
Added query swaps by refund address and extra-id
-
Fixed query swaps and affiliate export to indicate which fields are optional
Version 0.19.4:
- Added query swaps by any address field
Version 0.20.0:
- Removed GET /affiliate/:address/payouts
Version 0.20.1:
- Added price_quote_id to swap creation payload