NAV Navbar
json

Introduction

Welcome to the Escher developer documentation. Escher is a developer platform for cryptocurrency applications. It comprises three components: KYC, Liquidity, and Money Movement.

Sandbox Environment

For testing and development please access our sandbox environment at the URLs below. The sandbox environment requires different credentials than the production APIs. For sandbox credentials, email dev@iterative.capital. Orders sent to the sandbox are simulated, but not executed.

REST API

https://dev.api.i2trading.com/

Production Environment

For access, please email dev@iterative.capital

REST API

https://api.i2trading.com/

KYC-AML

All users must be verified through our KYC system before attempting a purchase.

The KYC Verification is part of our Trading API and uses the Trading API Base URL:

https://api.i2trading.com

Escher App

coming soon Escher App you will be able to use our Escher App to easily perform KYC verification for your users.

Escher Cashout Deeplink

Escher app currently allows users to cashout small balances (under $2.5k USD) to USD via the Lightning Network and Zelle. This can be actioned via our cashout deeplink. Want to have a branded integration in Escher App? Get in touch here

Request cashout via deeplink to Escher App locally.

Cashout Deeplink Example

https://hub.escher.app/cashout/<wallet name>?amount=<amount in sats>

This runs a call to Generate a BOLT-11 Lightning invoice from the Lightning Cashouts endpoint for a specified amount, defined by the wallet making the request. Escher will listen for payments to the payment hash generated by the invoice and automatically convert any satoshis sent to this hash into USD. A payment for that amount will then be sent to the user's registered Zelle address. Invoices and payment hashes are one-time use, so each cashout must request a new invoice.

Param Description
wallet (required) string. The wallet requesting the cashout (Breez, Zeus, etc.)
amount (required) float. The number of satoshis to specify in the invoice.

Request

{
  "wallet": "Breez",
  "amount": 10000,
}

Response

{ 
    "invoice": "lnbc1pvjluezpp5qqqsyqcesq5rqwzqfqqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqypqdpl2pkx2ctnv5sxxmmwwd5kgetjypeh2ursdae8g6twvus8g6rfwvs8qun0dfjkxaq8rkx3yf5tcsyz3d73gafnh3cax9rn449d9p5uxz9ezhhypd0elx87sjle52x86fux2ypatgddc6k63n7erqz25le42c4u4ecky03ylcqca784w"
}

Liquidity API

The REST API has endpoints for order management and trading.

REST API Production URL

https://api.i2trading.com

Requests

All requests and responses are application/json content type and use appropriate HTTP response status codes for success and failure.

Errors

{
  "message": "Invalid Symbol"
}

Unless otherwise stated, bad requests will recieve a response with HTTP 4xx status codes. The body will also contain a message parameter indicating the cause. Your language's HTTP library should be configured to provide message bodies for non-2xx requests so that you can read the message field from the body.

Common error codes

Status Code Description Possible Cause
400 Bad Request Invalid request format
401 Unauthorized Invalid access token or bad header
403 Forbidden You do not have access to the requested resource
404 Not Found Invalid URL
500 Internal Server Error Escher had a problem handling your request

Success

A successful response is indicated by HTTP status code 200 and may contain an optional body. If the response has a body it will be documented under each resource below.

Types

Timestamps

Unless otherwise specified, timestamps from the API are returned in ISO 8601 with microseconds. Make sure you can parse the following ISO 8601 format. Your language should have a library that can handle this without issues.

2019-06-04T16:53:40.357515+00:00

Numbers

Decimal numbers are returned as strings to preserve full precision across platforms. When making a request, it is recommended that you also convert your numbers to strings to avoid truncation and precision errors.

Integer numbers are unquoted.

Strings

All strings should be encoded in utf-8 unless otherwise specified.

IDs

Most identifiers are UUID unless otherwise specified. When making a request which requires a UUID, both forms (with and without dashes) are accepted.

11ffe56f-fce2-4fba-80ec-ab50a54f5eef or 11ffe56ffce24fba80ecab50a54f5eef

Authentication

Getting an Access Token

Registered users can retrieve an access token which is used to access the REST API. Access tokens are valid for one hour from the time they are retrieved. A new access token can be retrieved either by signing-in again or by using the RefreshToken in the sign-in response.

Request

{
  "email": "user@company.com",
  "password": "xxxxxxxx",
}
{
  "refreshToken": "ayJasdsadJKV1QiLCJlb........",
}

Response

{
  "AuthenticationResult": {
    "AccessToken": "eyJraWQiOiJMS3FrYUl..........",
    "ExpiresIn": 3600,
    "TokenType": "Bearer",
    "RefreshToken": "ayJasdsadJKV1QiLCJlb........",
    "IdToken": "ayJasdsadJKV1QiLCJlb..........."
  },
  "user_info": {
    "Username": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "sub": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "email_verified": "true",
    "phone_number_verified": "true",
    "nationality": "US",
    "last_name": "Doe",
    "account_type": "personal",
    "first_name": "John",
    "phone_number": "+xxxxxxxxxxx",
    "website": "www.example.com",
    "email": "john@doe.com"
  }
}

HTTP Request

POST /sign-in

The i2-ACCESS-KEY header is not required to access this endpoint. Only the Content-Type: application/json header must be set.

Attributes

The AccessToken attribute returned in the response is a JSON web token granting access to the REST and Websocket APIs (see creating a request). Access tokens are valid for one hour from the time they are retrieved.

Creating a Request

All REST requests must contain the following headers:

Header Content
i2-ACCESS-KEY Cognito AccessToken acquired from the /sign-in endpoint
Content-Type application/json

All request bodies should be valid JSON.

Orders

The API only supports Request for Quote (RFQ)-style orders. Quotes are valid for 10 seconds, and all accepted quotes are guaranteed to be filled at their quoted price and size before expiry.

Orders can only be placed for amounts less than or equal to your current unsettled trade limit. Trades that would cause you to exceed this limit are automatically rejected.

See Products for supported currency pairs.

Request for Quote (RFQ)

Get a firm quote with a set expiration time.

Request

{
  "product_id": "BTC-USD",
  "base_currency_size": "10.0",
  "side": "buy"
}

Response

{
  "quote_id": "6377c3da-d3e4-48d9-a503-b047e141606c",
  "product_id": "BTC-USD",
  "base_currency": "BTC",
  "quote_currency": "USD",
  "price": "8650.00",
  "base_currency_size": "10.0",
  "quote_currency_size": "86500.00",
  "side": "buy",
  "created_at": "2019-10-29T15:32:02.327857+00:00",
  "expiry": "2019-10-29T15:35:02.327857+00:00"
}

HTTP Request

POST /quotes

Param Description
product_id Product to trade (see GET /products)
base_currency_size Size to trade in base currency (i.e. BTC if product is BTC-USD).
side buy or sell

Trading a Quote

HTTP Request

POST /quotes/accept

Request

{
  "quote_id": "6377c3da-d3e4-48d9-a503-b047e141606c",
}

Response

{
  "success": true,
  "quote_id": "6c1b33f4-84fe-40a1-a017-a7991d46fe84",
  "order": {
    "id": "0f0665a9-4274-418e-ba93-3b8bd4d5b1bf",
    "created_at": "2020-01-29T19:39:03.513046+00:00",
    "product_id": "BTC-USD",
    "ord_type": "limit",
    "time_in_force": "FOK",
    "price": "8650.00",
    "size": "10.0",
    "side": "buy",
    "settle_from": "ADDRESS_Z",
    "settle_to": "ADDRESS",
    "status": "done",
    "executed_value": "86500.00"
  }
}
Param Description
quote_id Quote id

Order History

Get the status of the previous 25 orders.

[
  {
      "id": "4fd6e2c3-abc0-4084-b772-d7a9d4f8484e",
      "client_oid": "11f61551-f6ac-49f6-ac89-a2e66b65cf8d",
      "product_id": "BTC-USD",
      "price": "9400.00",
      "size": "10.00000000",
      "ord_type": "limit",
      "side": "buy",
      "time_in_force": "FOK",
      "created_at": "2019-10-02T14:51:56.145546+00:00",
      "status": "done",
      "done_at": "2019-10-02T14:51:56.154162+00:00",
      "done_reason": "filled",
      "filled_size": "10.00000000",
      "executed_value": "83295.40"
  },
  {
      "id": "675ee2bb-4cf2-43ec-9a72-3c4082acb3e9",
      "client_oid": "26d5d210-1bfb-44a7-82ef-ab92d64b32b6",
      "product_id": "BTC-USD",
      "price": "9400.00",
      "size": "10.00000000",
      "ord_type": "limit",
      "side": "buy",
      "time_in_force": "FOK",
      "created_at": "2019-10-02T14:46:49.924266+00:00",
      "status": "done",
      "done_at": "2019-10-02T14:46:49.930250+00:00",
      "done_reason": "filled",
      "filled_size": "10.00000000",
      "executed_value": "83236.80"
  }
]

HTTP Request

GET /orders

executed_value is the filled size multiplied by the fill price, which may be equal to or less than the order size.

Get a Specific Order

Get a single order by order id.

HTTP Request

GET /orders/<order-id>

Balances

Get your current unsettled trade balances.

{
  "balances": [
    {
      "currency": "BRL", 
      "balance": "-1964.42", 
      "net_notional_value": "-343.77350", 
      "notional_currency": "USD", 
      "reference_price": "0.175"
    }, 
    {
      "currency": "BTC", 
      "balance": "5.64370400", 
      "net_notional_value": "53375.2995517619636000", 
      "notional_currency": "USD", 
      "reference_price": "9457.49450215"
    }, 
    {
      "currency": "NGN", 
      "balance": "673483", 
      "net_notional_value": "1496.479226", 
      "notional_currency": "USD", 
      "reference_price": "0.002222"
    }, 
    {
      "currency": "USD", 
      "balance": "-30566.05", 
      "net_notional_value": "-30566.05", 
      "notional_currency": "USD", 
      "reference_price": "1"
    }
  ], 
  "limit": {
    "balance_limit": 250000, 
    "limit_currency": "USD"
  }
}

HTTP Request

GET /balances

Details

The balance_limit field indicates the total unsettled net notional value that the account is permitted to have before settling its trades. Trades that would cause the unsettled net notional balance to exceed this limit are rejected by the system. The limit is typically denoted in USD as indicated by the limit_currency field.

Negative balances indicate that Escher owes you money. When you a place trade, typically you will have a negative balance on one currency and a positive balance on another. When calculating unsettled trade limits, only positive balances are taken into account.

Products

Get a list of available pairs for trading.

[
  {
    "product": "BTC-BRL",
    "base_currency": "BTC",
    "quote_currency": "BRL",
    "base_min_size": "0.001",
    "base_max_size": "1000",
    "quote_increment": "0.01",
    "base_precision": 8,
    "quote_precision": 2
  },
  {
    "product": "BTC-USD",
    "base_currency": "BTC",
    "quote_currency": "USD",
    "base_min_size": "0.001",
    "base_max_size": "1000",
    "quote_increment": "0.01",
    "base_precision": 8,
    "quote_precision": 2
  },
  {
    "product": "DCR-USD",
    "base_currency": "DCR",
    "quote_currency": "USD",
    "base_min_size": "0.01",
    "base_max_size": "1000000",
    "quote_increment": "0.01",
    "base_precision": 4,
    "quote_precision": 2
  },
]

HTTP Request

GET /products

Details

The base_min_size and base_max_size fields define the min and max order size. The base_max_size is unrelated to trade limits on an account and serves as a sanity check for abnormally large orders.

The quote_increment field specifies the min order price as well as the price increment.

The order price must be a multiple of this increment (i.e. if the increment is 0.01, order prices of 0.001 or 0.021 would be rejected).

The base_precision and quote_precision fields define the number of decimal points of divisibility available for the respective currency. For example, BTC is divisible to 8 decimal points (eg. 0.00000001 BTC) and USD is divisible to 2 (eg. $0.01).

Products currently supported include BTC-USD, BTC-AED, BTC-BRL, DCR-USD, DCR-BTC, ETH-BRL, ETH-USD, ETH-BTC, USDT-BRL, USDT-USD

Money Movement

Coming soon. Escher is building infrastructure to automate USD settlement. Until then, we settle with clients via Wire Transfer.

Contact

To request access, get in touch here.