NAV Navbar
HTTP Curl Go JavaScript NodeJS Python Ruby
  • Bity API v2.0
  • Authentication
  • Orders
  • Currencies
  • Phone number login
  • Schemas
  • Bity API v2.0

    Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

    Status of this API

    This API is very close, but not exactly identical, to the Exchange API that will be released mid-March. In particular, in the version to be released mid-March, usage of a phone number will not be required.

    The version to be released mid-March will use a different URL endpoint. At that point, the version described here will be phased out. You will have to change the URL endpoint used by your application and will be required to perform minor modifications to your code. It will still be possible to place orders with a phone number, so no big change will be required.

    What is currently possible:

    What will become possible before the Exchange API release mid-March:

    What will be additionally enabled by the Exchange API mid-March:

    For higher level documentation, please consult the product page and the product guide.

    Base URLs:

    Terms of service Email: Bity Support Team Web: Bity Support Team

    Authentication

    Orders

    Estimate the amount of an order

    Code samples

    POST https://bity.com/api/v2/orders/estimate HTTP/1.1
    Host: bity.com
    Content-Type: application/json
    Accept: application/json
    
    
    curl -X POST https://bity.com/api/v2/orders/estimate \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json' \
      --data '{
      "input": {
        "currency": "BTC",
        "amount": "1.00000000"
      },
      "output": {
        "currency": "EUR"
      }
    }'
    
    
    package main
    
    import (
           "bytes"
           "net/http"
    )
    
    func main() {
    
        headers := map[string][]string{
            "Content-Type": []string{"application/json"},
            "Accept": []string{"application/json"},
    
        }
    
        data := bytes.NewBuffer([]byte{jsonReq})
        req, err := http.NewRequest("POST", "https://bity.com/api/v2/orders/estimate", data)
        req.Header = headers
    
        client := &http.Client{}
        resp, err := client.Do(req)
        // ...
    }
    
    
    var headers = {
      'Content-Type': 'application/json',
      'Accept': 'application/json'
    };
    
    var inputBody = {
      "input": {
        "currency": "BTC",
        "amount": "1.00000000"
      },
      "output": {
        "currency": "EUR"
      }
    };
    
    $.ajax({
      url: 'https://bity.com/api/v2/orders/estimate',
      method: 'post',
      data: JSON.stringify(inputBody),
      headers: headers,
      success: function(data) {
        console.log(JSON.stringify(data));
      }
    })
    
    
    const fetch = require('node-fetch');
    const inputBody = {
      "input": {
        "currency": "BTC",
        "amount": "1.00000000"
      },
      "output": {
        "currency": "EUR"
      }
    };
    const headers = {
      'Content-Type': 'application/json',
      'Accept': 'application/json'
    };
    
    fetch('https://bity.com/api/v2/orders/estimate',
    {
      method: 'POST',
      body: JSON.stringify(inputBody),
      headers: headers
    }).then(function(res) {
        return res.json();
    }).then(function(body) {
        console.log(body);
    });
    
    
    import json
    import requests
    
    headers = {
      'Content-Type': 'application/json',
      'Accept': 'application/json'
    }
    data = {
      "input": {
        "currency": "BTC",
        "amount": "1.00000000"
      },
      "output": {
        "currency": "EUR"
      }
    }
    
    r = requests.post('https://bity.com/api/v2/orders/estimate',
        params={},
        data=json.dumps(data),
        headers=headers)
    
    print(r.json())
    
    
    require 'rest-client'
    require 'json'
    
    headers = {
      'Content-Type' => 'application/json',
      'Accept' => 'application/json'
    }
    
    result = RestClient.post 'https://bity.com/api/v2/orders/estimate',
      params: {
      }, headers: headers
    
    p JSON.parse(result)
    
    

    POST /orders/estimate

    The endpoint is similar to the endpoints allowing an order to be placed. However, only the currencies and the input or output amount are specified in the request.

    Estimate the output amount corresponding to an input amount

    To estimate the output amount simply place the amount in the input.

    Estimate the input amount corresponding to an output amount

    To estimate the input amount simply place the amount in the output.

    Body parameter

    Example specifying the input amount and expecting to get the output amount.

    {
      "input": {
        "currency": "BTC",
        "amount": "1.00000000"
      },
      "output": {
        "currency": "EUR"
      }
    }
    

    Parameters

    Name In Type Required Description
    input body CurrencyAmount false none
    » currency body CurrencyCode true none
    » amount body string true none
    output body CurrencyAmount false none

    Enumerated Values

    Parameter Value
    » currency BTC
    » currency ETH
    » currency REP
    » currency EUR
    » currency CHF

    Example responses

    Example response when specifying input or output.

    {
      "input": {
        "currency": "BTC",
        "amount": "1.00000000"
      },
      "output": {
        "currency": "EUR",
        "amount": "3087.86"
      }
    }
    

    Responses

    Status Meaning Description Schema
    200 OK Successful operation Inline
    400 Bad Request Malformed request.
    Invalid currency code.
    Invalid currency pair.
    Invalid amount.
    None

    Response Schema

    Status Code 200

    Name Type Required Restrictions Description
    » input CurrencyAmount false none none
    »» currency CurrencyCode true none none
    »» amount string true none none
    » output CurrencyAmount false none none

    Enumerated Values

    Property Value
    currency BTC
    currency ETH
    currency REP
    currency EUR
    currency CHF

    Place an order

    Code samples

    POST https://bity.com/api/v2/orders/phone HTTP/1.1
    Host: bity.com
    Content-Type: application/json
    
    
    curl -X POST https://bity.com/api/v2/orders/phone \
      -H 'Content-Type: application/json' \
      -H 'X-Phone-Token: API_KEY' \
      --data '{
      "input": {
        "amount": "0.5",
        "currency": "ETH",
        "type": "crypto_address",
        "crypto_address": "0xf35074bbd0a9aee46f4ea137971feec024ab7048"
      },
      "output": {
        "currency": "CHF",
        "type": "bank_account",
        "iban": "CH3600000000000000000",
        "bic_swift": "CHAAAABBXXX",
        "owner": {
          "name": "John Doe",
          "address": "Brückenstrasse 12",
          "zip": "3000",
          "city": "Bern",
          "country": "CH"
        }
      }
    }'
    
    
    package main
    
    import (
           "bytes"
           "net/http"
    )
    
    func main() {
    
        headers := map[string][]string{
            "Content-Type": []string{"application/json"},
            "X-Phone-Token": []string{"API_KEY"},
    
        }
    
        data := bytes.NewBuffer([]byte{jsonReq})
        req, err := http.NewRequest("POST", "https://bity.com/api/v2/orders/phone", data)
        req.Header = headers
    
        client := &http.Client{}
        resp, err := client.Do(req)
        // ...
    }
    
    
    var headers = {
      'Content-Type': 'application/json',
      'X-Phone-Token': 'API_KEY'
    };
    
    var inputBody = {
      "input": {
        "amount": "0.5",
        "currency": "ETH",
        "type": "crypto_address",
        "crypto_address": "0xf35074bbd0a9aee46f4ea137971feec024ab7048"
      },
      "output": {
        "currency": "CHF",
        "type": "bank_account",
        "iban": "CH3600000000000000000",
        "bic_swift": "CHAAAABBXXX",
        "owner": {
          "name": "John Doe",
          "address": "Brückenstrasse 12",
          "zip": "3000",
          "city": "Bern",
          "country": "CH"
        }
      }
    };
    
    $.ajax({
      url: 'https://bity.com/api/v2/orders/phone',
      method: 'post',
      data: JSON.stringify(inputBody),
      headers: headers,
      success: function(data) {
        console.log(JSON.stringify(data));
      }
    })
    
    
    const fetch = require('node-fetch');
    const inputBody = {
      "input": {
        "amount": "0.5",
        "currency": "ETH",
        "type": "crypto_address",
        "crypto_address": "0xf35074bbd0a9aee46f4ea137971feec024ab7048"
      },
      "output": {
        "currency": "CHF",
        "type": "bank_account",
        "iban": "CH3600000000000000000",
        "bic_swift": "CHAAAABBXXX",
        "owner": {
          "name": "John Doe",
          "address": "Brückenstrasse 12",
          "zip": "3000",
          "city": "Bern",
          "country": "CH"
        }
      }
    };
    const headers = {
      'Content-Type': 'application/json',
      'X-Phone-Token': 'API_KEY'
    };
    
    fetch('https://bity.com/api/v2/orders/phone',
    {
      method: 'POST',
      body: JSON.stringify(inputBody),
      headers: headers
    }).then(function(res) {
        return res.json();
    }).then(function(body) {
        console.log(body);
    });
    
    
    import json
    import requests
    
    headers = {
      'Content-Type': 'application/json',
      'X-Phone-Token': 'API_KEY'
    }
    data = {
      "input": {
        "amount": "0.5",
        "currency": "ETH",
        "type": "crypto_address",
        "crypto_address": "0xf35074bbd0a9aee46f4ea137971feec024ab7048"
      },
      "output": {
        "currency": "CHF",
        "type": "bank_account",
        "iban": "CH3600000000000000000",
        "bic_swift": "CHAAAABBXXX",
        "owner": {
          "name": "John Doe",
          "address": "Brückenstrasse 12",
          "zip": "3000",
          "city": "Bern",
          "country": "CH"
        }
      }
    }
    
    r = requests.post('https://bity.com/api/v2/orders/phone',
        params={},
        data=json.dumps(data),
        headers=headers)
    
    print(r.json())
    
    
    require 'rest-client'
    require 'json'
    
    headers = {
      'Content-Type' => 'application/json',
      'X-Phone-Token' => 'API_KEY'
    }
    
    result = RestClient.post 'https://bity.com/api/v2/orders/phone',
      params: {
      }, headers: headers
    
    p JSON.parse(result)
    
    

    POST /orders/phone

    It is possible to specify amount in the input or output in which case the corresponding input or output amount will be computed. The input or output amount can be estimated beforehand using the dedicated endpoint, see "Estimate the amount of an order". Please note that without KYC, crypto-addresses, phones and bank accounts are limited to a volume of 5000 CHF over a period of 365 days. We are unfortunately currently unable to send EUR payments to all IBANs. At this time, crypto-to-EUR orders are only possible with IBANs of the following countries: Austria, Belgium, Bulgaria, Croatia, Cyprus, Czech Republic, Denmark, Estonia, Finland, France, Germany, Greece, Hungary, Iceland, Ireland, Italy, Latvia, Liechtenstein, Lithuania, Luxembourg, Malta, Monaco, Netherlands, Norway, Poland, Portugal, Romania, San Marino, Spain, Slovakia, Slovenia, Sweden, Switzerland, UK and Northern Ireland. This list of supported countries for EUR output will grow.

    Body parameter

    Crypto-to-fiat example.

    {
      "input": {
        "amount": "0.5",
        "currency": "ETH",
        "type": "crypto_address",
        "crypto_address": "0xf35074bbd0a9aee46f4ea137971feec024ab7048"
      },
      "output": {
        "currency": "CHF",
        "type": "bank_account",
        "iban": "CH3600000000000000000",
        "bic_swift": "CHAAAABBXXX",
        "owner": {
          "name": "John Doe",
          "address": "Brückenstrasse 12",
          "zip": "3000",
          "city": "Bern",
          "country": "CH"
        }
      }
    }
    

    Parameters

    Name In Type Required Description
    input body PlacedOrderInputOutput false none
    » amount body string false none
    » currency body CurrencyCode true none
    » type body PlacedOrderInputOutputType true none
    » crypto_address body string false Only valid if type is crypto_address.
    » iban body string false Only valid if type is bank_account.
    » bic_swift body string false Only valid if type is bank_account.
    » owner body object false Only valid if type is bank_account.
    »» name body string false none
    »» address body string false none
    »» address_complement body string false none
    »» zip body string false none
    »» city body string false none
    »» state body string false none
    »» country body string false Must contain the two-letter country code (ISO 3166-1 alpha-2).
    » output body PlacedOrderInputOutput false none

    Enumerated Values

    Parameter Value
    » currency BTC
    » currency ETH
    » currency REP
    » currency EUR
    » currency CHF
    » type crypto_address
    » type bank_account

    Responses

    Status Meaning Description Schema
    201 Created The order has been successfully created.
    The Location header contains the URI (which can be relative) at which the order status and details can be retrieved. That is the Location header is meant to be interpreted as per RFC 7231 section 7.1.2. None
    400 Bad Request Following cases:
    Unsupported currency pair.
    Quota exceeded for the phone, bank account or crypto-address.
    Internal error.
    None

    List previously placed orders

    Code samples

    GET https://bity.com/api/v2/orders HTTP/1.1
    Host: bity.com
    Accept: application/json
    
    
    curl -X GET https://bity.com/api/v2/orders \
      -H 'Accept: application/json' \
      -H 'X-Phone-Token: API_KEY'
    
    
    package main
    
    import (
           "bytes"
           "net/http"
    )
    
    func main() {
    
        headers := map[string][]string{
            "Accept": []string{"application/json"},
            "X-Phone-Token": []string{"API_KEY"},
    
        }
    
        data := bytes.NewBuffer([]byte{jsonReq})
        req, err := http.NewRequest("GET", "https://bity.com/api/v2/orders", data)
        req.Header = headers
    
        client := &http.Client{}
        resp, err := client.Do(req)
        // ...
    }
    
    
    var headers = {
      'Accept': 'application/json',
      'X-Phone-Token': 'API_KEY'
    };
    
    $.ajax({
      url: 'https://bity.com/api/v2/orders',
      method: 'get',
    
      headers: headers,
      success: function(data) {
        console.log(JSON.stringify(data));
      }
    })
    
    
    const fetch = require('node-fetch');
    
    const headers = {
      'Accept': 'application/json',
      'X-Phone-Token': 'API_KEY'
    };
    
    fetch('https://bity.com/api/v2/orders',
    {
      method: 'GET',
      headers: headers
    }).then(function(res) {
        return res.json();
    }).then(function(body) {
        console.log(body);
    });
    
    
    import json
    import requests
    
    headers = {
      'Accept': 'application/json',
      'X-Phone-Token': 'API_KEY'
    }
    
    r = requests.get('https://bity.com/api/v2/orders',
        params={},
    
        headers=headers)
    
    print(r.json())
    
    
    require 'rest-client'
    require 'json'
    
    headers = {
      'Accept' => 'application/json',
      'X-Phone-Token' => 'API_KEY'
    }
    
    result = RestClient.get 'https://bity.com/api/v2/orders',
      params: {
      }, headers: headers
    
    p JSON.parse(result)
    
    

    GET /orders

    Get a list of previously placed orders. This endpoint can be called with both phone and customer authentication. Depending on the authentication method used different orders will be returned.

    Example responses

    200 Response

    {
      "orders": [
        {
          "id": "0123456789abcdefghijk",
          "payment_details": {
            "type": "crypto_address",
            "crypto_address": "0xf35074bbd0a9aee46f4ea137971feec024ab7048"
          },
          "input": {
            "currency": "ETH",
            "amount": "0.5",
            "type": "crypto_address",
            "crypto_address": "0x24305d091f79ee490a34de080b0db5773be5bef4"
          },
          "output": {
            "currency": "CHF",
            "amount": "104.95",
            "type": "bank_account",
            "iban": "CH3600000000000000000",
            "bic_swift": "BCNNCH22",
            "owner": {
              "name": "John Doe",
              "country": "CH",
              "city": "Neuchatel",
              "address": "Rue des Fahrys 2"
            }
          },
          "timestamp_created": "2019-01-24T13:14:07.368Z",
          "timestamp_cancelled": "2019-01-25T01:06:11.632Z",
          "legacy_status": "CANC"
        }
      ]
    }
    

    Responses

    Status Meaning Description Schema
    200 OK Successful operation. Inline

    Response Schema

    Status Code 200

    Name Type Required Restrictions Description
    » orders [PlacedOrder] false none [Details of a previous placed order]
    »» id string false none Unique ID of the order
    »» input PlacedOrderInputOutput true none none
    »»» amount string false none none
    »»» currency CurrencyCode true none none
    »»» type PlacedOrderInputOutputType true none none
    »»» crypto_address string false none Only valid if type is crypto_address.
    »»» iban string false none Only valid if type is bank_account.
    »»» bic_swift string false none Only valid if type is bank_account.
    »»» owner object false none Only valid if type is bank_account.
    »»»» name string false none none
    »»»» address string false none none
    »»»» address_complement string false none none
    »»»» zip string false none none
    »»»» city string false none none
    »»»» state string false none none
    »»»» country string false none Must contain the two-letter country code (ISO 3166-1 alpha-2).
    »»» message_to_sign MessageToSign false none A message to be signed. The signature must be sent in the body of a POST request to the URL specified by "signature_submission_url".
    »»»» body string true none none
    »»»» signature_submission_url string true none none
    »»» output PlacedOrderInputOutput true none none
    »»» payment_details object false none none
    »»»» type PlacedOrderInputOutputType false none none
    »»»» crypto_address string false none Only valid if type is crypto_address.
    »»»» account_number string false none none
    »»»» bank_address string false none none
    »»»» bank_code string false none none
    »»»» iban string false none none
    »»»» recipient string false none none
    »»»» swift_bic string false none none
    »»» timestamp_created string(date-time) true none In order for the order to be executed exactly as shown, the input must be paid within ten minutes of timestamp_created with a single transaction. If the amount is paid after the ten-minute window, the output amount might change during execution.
    »»» timestamp_cancelled string(date-time) false none Date and time at which the order was cancelled.
    »»» legacy_status string false none none

    Enumerated Values

    Property Value
    currency BTC
    currency ETH
    currency REP
    currency EUR
    currency CHF
    type crypto_address
    type bank_account
    type crypto_address
    type bank_account
    legacy_status OPEN
    legacy_status CANC
    legacy_status ERR
    legacy_status EXEC
    legacy_status PART
    legacy_status RFND

    Get the details of an order

    Code samples

    GET https://bity.com/api/v2/orders/{order_uuid} HTTP/1.1
    Host: bity.com
    Accept: application/json
    
    
    curl -X GET https://bity.com/api/v2/orders/{order_uuid} \
      -H 'Accept: application/json' \
      -H 'X-Phone-Token: API_KEY'
    
    
    package main
    
    import (
           "bytes"
           "net/http"
    )
    
    func main() {
    
        headers := map[string][]string{
            "Accept": []string{"application/json"},
            "X-Phone-Token": []string{"API_KEY"},
    
        }
    
        data := bytes.NewBuffer([]byte{jsonReq})
        req, err := http.NewRequest("GET", "https://bity.com/api/v2/orders/{order_uuid}", data)
        req.Header = headers
    
        client := &http.Client{}
        resp, err := client.Do(req)
        // ...
    }
    
    
    var headers = {
      'Accept': 'application/json',
      'X-Phone-Token': 'API_KEY'
    };
    
    $.ajax({
      url: 'https://bity.com/api/v2/orders/{order_uuid}',
      method: 'get',
    
      headers: headers,
      success: function(data) {
        console.log(JSON.stringify(data));
      }
    })
    
    
    const fetch = require('node-fetch');
    
    const headers = {
      'Accept': 'application/json',
      'X-Phone-Token': 'API_KEY'
    };
    
    fetch('https://bity.com/api/v2/orders/{order_uuid}',
    {
      method: 'GET',
      headers: headers
    }).then(function(res) {
        return res.json();
    }).then(function(body) {
        console.log(body);
    });
    
    
    import json
    import requests
    
    headers = {
      'Accept': 'application/json',
      'X-Phone-Token': 'API_KEY'
    }
    
    r = requests.get('https://bity.com/api/v2/orders/{order_uuid}',
        params={},
    
        headers=headers)
    
    print(r.json())
    
    
    require 'rest-client'
    require 'json'
    
    headers = {
      'Accept' => 'application/json',
      'X-Phone-Token' => 'API_KEY'
    }
    
    result = RestClient.get 'https://bity.com/api/v2/orders/{order_uuid}',
      params: {
      }, headers: headers
    
    p JSON.parse(result)
    
    

    GET /orders/{order_uuid}

    Please note the following:

    If the amount paid is not exactly the input amount, we can be required to cancel the order, or the output amount will be adjusted and extra fees could be charged.
    If it is sent in multiple transactions, we can be required to cancel the order and extra processing fees could be charged.

    Output address signature

    When the customer is not authenticated or has not gone through the KYC process, crypto-to-crypto and fiat-to-crypto orders require the signature of a message by the output address for the order to become executable. When such a signature is required "message_to_sign" is included in the response and the payment details will not be provided until the signature of the message is submitted.

    Input and output objects

    The input type and output type can be one of "crypto_address" or "bank_account".
    In case it is "crypto_address" the object additionally contains "crypto_address".
    In case it is "bank_account" the object additionally contains "iban".
    Whenever the input object contains iban or crypto_address, the input must be paid from the corresponding object. If this is not the case, we can be required to cancel the order and extra fees can be charged.

    Payment details

    This object describes how to pay the input amount. There are two different possible types of payment details: "crypto_address" and "bank_account". Both types are described bellow. The amount and the associated currency is found in the input object.

    Cryptoaddress

    When the payment must be made to a cryptoaddress, the type is "crypto_address" and the address to use as a destination address is found in the "crypto_address" attribute.

    Bank account

    When the payment must be made to a bank account, the type is "bank_account". In most cases the banks involved in sending, transmitting and receiving the payment will require the IBAN, SWIFT code and the bank account owner name and address to process the payment. This is reflected by the information provided in the response:

    Legacy status

    This paragraph is non-normative. The legacy_status described here will likely be removed from this version of the API. There is additionally absolutely no guarantee that legacy_status is going to be present in the response. Currently, legacy_status can be "EXEC" when the order has been executed, "OPEN" when the order has not yet been executed and "CANC" when the order has been cancelled.

    Parameters

    Name In Type Required Description
    order_uuid path undefined true Unique ID of the placed order. It can be obtained from the Location header after successfully placing an order.

    Example responses

    200 Response

    {
      "id": "0123456789abcdefghijk",
      "payment_details": {
        "type": "crypto_address",
        "crypto_address": "0xf35074bbd0a9aee46f4ea137971feec024ab7048"
      },
      "input": {
        "currency": "ETH",
        "amount": "0.5",
        "type": "crypto_address",
        "crypto_address": "0x24305d091f79ee490a34de080b0db5773be5bef4"
      },
      "output": {
        "currency": "CHF",
        "amount": "104.95",
        "type": "bank_account",
        "iban": "CH3600000000000000000",
        "bic_swift": "BCNNCH22",
        "owner": {
          "name": "John Doe",
          "country": "CH",
          "city": "Neuchatel",
          "address": "Rue des Fahrys 2"
        }
      },
      "timestamp_created": "2019-01-24T13:14:07.368Z",
      "timestamp_cancelled": "2019-01-25T01:06:11.632Z",
      "legacy_status": "CANC"
    }
    

    Responses

    Status Meaning Description Schema
    200 OK Order successfully retrieved. PlacedOrder
    400 Bad Request Order with such ID not found. None

    Currencies

    List currencies

    Code samples

    GET https://bity.com/api/v2/currencies HTTP/1.1
    Host: bity.com
    Accept: application/json
    
    
    curl -X GET https://bity.com/api/v2/currencies \
      -H 'Accept: application/json'
    
    
    package main
    
    import (
           "bytes"
           "net/http"
    )
    
    func main() {
    
        headers := map[string][]string{
            "Accept": []string{"application/json"},
    
        }
    
        data := bytes.NewBuffer([]byte{jsonReq})
        req, err := http.NewRequest("GET", "https://bity.com/api/v2/currencies", data)
        req.Header = headers
    
        client := &http.Client{}
        resp, err := client.Do(req)
        // ...
    }
    
    
    var headers = {
      'Accept': 'application/json'
    };
    
    $.ajax({
      url: 'https://bity.com/api/v2/currencies',
      method: 'get',
    
      headers: headers,
      success: function(data) {
        console.log(JSON.stringify(data));
      }
    })
    
    
    const fetch = require('node-fetch');
    
    const headers = {
      'Accept': 'application/json'
    };
    
    fetch('https://bity.com/api/v2/currencies',
    {
      method: 'GET',
      headers: headers
    }).then(function(res) {
        return res.json();
    }).then(function(body) {
        console.log(body);
    });
    
    
    import json
    import requests
    
    headers = {
      'Accept': 'application/json'
    }
    
    r = requests.get('https://bity.com/api/v2/currencies',
        params={},
    
        headers=headers)
    
    print(r.json())
    
    
    require 'rest-client'
    require 'json'
    
    headers = {
      'Accept' => 'application/json'
    }
    
    result = RestClient.get 'https://bity.com/api/v2/currencies',
      params: {
      }, headers: headers
    
    p JSON.parse(result)
    
    

    GET /currencies

    Parameters

    Name In Type Required Description
    tags query CurrencyTag false Comma-separated list of tags. Currencies that contain all tags will be filtered.

    Enumerated Values

    Parameter Value
    tags crypto
    tags erc20
    tags ethereum
    tags fiat

    Example responses

    List currencies without any filter.

    {
      "currencies": [
        {
          "code": "BTC",
          "tags": [
            "crypto"
          ]
        },
        {
          "code": "CHF",
          "tags": [
            "fiat"
          ]
        },
        {
          "code": "ETH",
          "tags": [
            "crypto",
            "ethereum"
          ]
        },
        {
          "code": "EUR",
          "tags": [
            "fiat"
          ]
        },
        {
          "code": "REP",
          "tags": [
            "crypto",
            "ethereum",
            "erc20"
          ]
        }
      ]
    }
    

    List currencies filtering by "fiat".

    [
      {
        "code": "CHF",
        "tags": [
          "fiat"
        ]
      },
      {
        "code": "EUR",
        "tags": [
          "fiat"
        ]
      }
    ]
    

    Responses

    Status Meaning Description Schema
    200 OK Successful operation Inline

    Response Schema

    Status Code 200

    Name Type Required Restrictions Description
    » currencies [Currency] false none none
    »» code CurrencyCode true none none
    »» tags [CurrencyTag] true none none

    Enumerated Values

    Property Value
    code BTC
    code ETH
    code REP
    code EUR
    code CHF

    Get a single currency

    Code samples

    GET https://bity.com/api/v2/currencies/{currency} HTTP/1.1
    Host: bity.com
    Accept: application/json
    
    
    curl -X GET https://bity.com/api/v2/currencies/{currency} \
      -H 'Accept: application/json'
    
    
    package main
    
    import (
           "bytes"
           "net/http"
    )
    
    func main() {
    
        headers := map[string][]string{
            "Accept": []string{"application/json"},
    
        }
    
        data := bytes.NewBuffer([]byte{jsonReq})
        req, err := http.NewRequest("GET", "https://bity.com/api/v2/currencies/{currency}", data)
        req.Header = headers
    
        client := &http.Client{}
        resp, err := client.Do(req)
        // ...
    }
    
    
    var headers = {
      'Accept': 'application/json'
    };
    
    $.ajax({
      url: 'https://bity.com/api/v2/currencies/{currency}',
      method: 'get',
    
      headers: headers,
      success: function(data) {
        console.log(JSON.stringify(data));
      }
    })
    
    
    const fetch = require('node-fetch');
    
    const headers = {
      'Accept': 'application/json'
    };
    
    fetch('https://bity.com/api/v2/currencies/{currency}',
    {
      method: 'GET',
      headers: headers
    }).then(function(res) {
        return res.json();
    }).then(function(body) {
        console.log(body);
    });
    
    
    import json
    import requests
    
    headers = {
      'Accept': 'application/json'
    }
    
    r = requests.get('https://bity.com/api/v2/currencies/{currency}',
        params={},
    
        headers=headers)
    
    print(r.json())
    
    
    require 'rest-client'
    require 'json'
    
    headers = {
      'Accept' => 'application/json'
    }
    
    result = RestClient.get 'https://bity.com/api/v2/currencies/{currency}',
      params: {
      }, headers: headers
    
    p JSON.parse(result)
    
    

    GET /currencies/{currency}

    Parameters

    Name In Type Required Description
    currency path CurrencyCode true none

    Enumerated Values

    Parameter Value
    currency BTC
    currency ETH
    currency REP
    currency EUR
    currency CHF

    Example responses

    200 Response

    {
      "code": "ETH",
      "tags": [
        "crypto",
        "ethereum"
      ]
    }
    

    Responses

    Status Meaning Description Schema
    200 OK Successful operation Currency
    404 Not Found Currency not found or unsupported None

    List currency pairs

    Code samples

    GET https://bity.com/api/v2/pairs HTTP/1.1
    Host: bity.com
    Accept: application/json
    
    
    curl -X GET https://bity.com/api/v2/pairs \
      -H 'Accept: application/json'
    
    
    package main
    
    import (
           "bytes"
           "net/http"
    )
    
    func main() {
    
        headers := map[string][]string{
            "Accept": []string{"application/json"},
    
        }
    
        data := bytes.NewBuffer([]byte{jsonReq})
        req, err := http.NewRequest("GET", "https://bity.com/api/v2/pairs", data)
        req.Header = headers
    
        client := &http.Client{}
        resp, err := client.Do(req)
        // ...
    }
    
    
    var headers = {
      'Accept': 'application/json'
    };
    
    $.ajax({
      url: 'https://bity.com/api/v2/pairs',
      method: 'get',
    
      headers: headers,
      success: function(data) {
        console.log(JSON.stringify(data));
      }
    })
    
    
    const fetch = require('node-fetch');
    
    const headers = {
      'Accept': 'application/json'
    };
    
    fetch('https://bity.com/api/v2/pairs',
    {
      method: 'GET',
      headers: headers
    }).then(function(res) {
        return res.json();
    }).then(function(body) {
        console.log(body);
    });
    
    
    import json
    import requests
    
    headers = {
      'Accept': 'application/json'
    }
    
    r = requests.get('https://bity.com/api/v2/pairs',
        params={},
    
        headers=headers)
    
    print(r.json())
    
    
    require 'rest-client'
    require 'json'
    
    headers = {
      'Accept' => 'application/json'
    }
    
    result = RestClient.get 'https://bity.com/api/v2/pairs',
      params: {
      }, headers: headers
    
    p JSON.parse(result)
    
    

    GET /pairs

    Gets a list of all the currency pairs that can be traded through the Bity platform.

    Parameters

    Name In Type Required Description
    input query string false Retrieve all pairs for given input currency code. This parameter can be repeated several times to match many input currencies.
    output query string false Retrieve all pairs for given output currency code. This parameter can be repeated several times to match many output currencies.
    enabled query string false Retrieve all pairs that are enabled for trading or not.

    Example responses

    List currency pairs without any filter.

    {
      "pairs": [
        {
          "input": "BTC",
          "output": "CHF",
          "enabled": true
        },
        {
          "input": "CHF",
          "output": "BTC",
          "enabled": true
        },
        {
          "input": "ETH",
          "output": "REP",
          "enabled": true
        },
        {
          "input": "EUR",
          "output": "ETH",
          "enabled": true
        }
      ]
    }
    

    Responses

    Status Meaning Description Schema
    200 OK Successful operation Inline

    Response Schema

    Status Code 200

    Name Type Required Restrictions Description
    » pairs [CurrencyPair] false none none
    »» input CurrencyCode true none none
    »» output CurrencyCode true none none
    »» enabled boolean true none none

    Enumerated Values

    Property Value
    input BTC
    input ETH
    input REP
    input EUR
    input CHF
    output BTC
    output ETH
    output REP
    output EUR
    output CHF

    Phone number login

    Log in with a phone number

    Code samples

    POST https://bity.com/api/v2/login/phone HTTP/1.1
    Host: bity.com
    Content-Type: application/json
    Accept: application/json
    X-Phone-Token: 34234fivpd3m21jllj9sf912fsdf
    
    
    curl -X POST https://bity.com/api/v2/login/phone \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json' \
      -H 'X-Phone-Token: 34234fivpd3m21jllj9sf912fsdf' \
      --data '{
      "phone_number": "+41000997321"
    }'
    
    
    package main
    
    import (
           "bytes"
           "net/http"
    )
    
    func main() {
    
        headers := map[string][]string{
            "Content-Type": []string{"application/json"},
            "Accept": []string{"application/json"},
            "X-Phone-Token": []string{"34234fivpd3m21jllj9sf912fsdf"},
    
        }
    
        data := bytes.NewBuffer([]byte{jsonReq})
        req, err := http.NewRequest("POST", "https://bity.com/api/v2/login/phone", data)
        req.Header = headers
    
        client := &http.Client{}
        resp, err := client.Do(req)
        // ...
    }
    
    
    var headers = {
      'Content-Type': 'application/json',
      'Accept': 'application/json',
      'X-Phone-Token': '34234fivpd3m21jllj9sf912fsdf'
    };
    
    var inputBody = {
      "phone_number": "+41000997321"
    };
    
    $.ajax({
      url: 'https://bity.com/api/v2/login/phone',
      method: 'post',
      data: JSON.stringify(inputBody),
      headers: headers,
      success: function(data) {
        console.log(JSON.stringify(data));
      }
    })
    
    
    const fetch = require('node-fetch');
    const inputBody = {
      "phone_number": "+41000997321"
    };
    const headers = {
      'Content-Type': 'application/json',
      'Accept': 'application/json',
      'X-Phone-Token': '34234fivpd3m21jllj9sf912fsdf'
    };
    
    fetch('https://bity.com/api/v2/login/phone',
    {
      method: 'POST',
      body: JSON.stringify(inputBody),
      headers: headers
    }).then(function(res) {
        return res.json();
    }).then(function(body) {
        console.log(body);
    });
    
    
    import json
    import requests
    
    headers = {
      'Content-Type': 'application/json',
      'Accept': 'application/json',
      'X-Phone-Token': '34234fivpd3m21jllj9sf912fsdf'
    }
    data = {
      "phone_number": "+41000997321"
    }
    
    r = requests.post('https://bity.com/api/v2/login/phone',
        params={},
        data=json.dumps(data),
        headers=headers)
    
    print(r.json())
    
    
    require 'rest-client'
    require 'json'
    
    headers = {
      'Content-Type' => 'application/json',
      'Accept' => 'application/json',
      'X-Phone-Token' => '34234fivpd3m21jllj9sf912fsdf'
    }
    
    result = RestClient.post 'https://bity.com/api/v2/login/phone',
      params: {
      }, headers: headers
    
    p JSON.parse(result)
    
    

    POST /login/phone

    Establishing a session is done in two steps:

    1. Sending a random code to the phone number.
    2. Sending the random code back to the service.

    Request 1: receive the phone token

    All following requests must specify the value of phone_token in the X-Phone-Token HTTP header.

    The value of the phone token is a random string that can be used as is in an HTTP header.

    An SMS will be delivered to the phone number. Please be patient, it can take a few minutes for the SMS to be delivered.

    Request 2: submit the received sms code

    The value of the tan must be the random code that the phone number received.

    If successful, a 204 (no content) status code is returned and can be used with the same X-Phone-Token header.

    Body parameter

    Example input body for first request.

    {
      "phone_number": "+41000997321"
    }
    

    Parameters

    Name In Type Required Description
    X-Phone-Token header string false Token obtained in the first request to this endpoint that represents this phone session.
    phone_number body string false Phone number to sign in with. I has to be in international format with the corresponding country prefix. Use this parameter in the first request to this endpoint in order to receive the SMS code.
    tan body string false Code received by SMS, sent to the phone specified in the first request to this endpoint. Use this parameter in the second request to this endpoint.

    Example responses

    Example of received phone token in the first request

    {
      "phone_token": "34234fivpd3m21jllj9sf912fsdf"
    }
    

    Responses

    Status Meaning Description Schema
    200 OK The phone session has been created, but it is not active yet. In order to activate a second request to this endpoint is necessary including the phone token in the headers, and the tan code in the body. Inline
    204 No Content The phone session has been established, or there was an active session with the provided phone. None
    403 Forbidden The submitted tan value does not correspond to the code sent by SMS to the phone number. You can try again with the correct code. None
    429 Too Many Requests Too many consecutive attempts to request a phone token. Wait a few minutes and try again. None

    Response Schema

    Status Code 200

    Name Type Required Restrictions Description
    » phone_token string false none Phone token to be used in the second request to this endpoint. It will expire after 24h.

    Schemas

    Currency

    {
      "code": "ETH",
      "tags": [
        "crypto",
        "ethereum"
      ]
    }
    
    

    Properties

    Name Type Required Restrictions Description
    code CurrencyCode true none none
    tags [CurrencyTag] true none none

    CurrencyAmount

    {
      "amount": "0.334098188",
      "currency": "BTC"
    }
    
    

    Properties

    Name Type Required Restrictions Description
    currency CurrencyCode true none none
    amount string true none none

    CurrencyCode

    "BTC"
    
    

    Properties

    Name Type Required Restrictions Description
    anonymous string false none none

    Enumerated Values

    Property Value
    anonymous BTC
    anonymous ETH
    anonymous REP
    anonymous EUR
    anonymous CHF

    CurrencyPair

    {
      "enabled": true,
      "input": "BTC",
      "output": "CHF"
    }
    
    

    Properties

    Name Type Required Restrictions Description
    input CurrencyCode true none none
    output CurrencyCode true none none
    enabled boolean true none none

    CurrencyTag

    "crypto"
    
    

    Properties

    Name Type Required Restrictions Description
    anonymous string false none none

    Enumerated Values

    Property Value
    anonymous crypto
    anonymous erc20
    anonymous ethereum
    anonymous fiat

    MessageToSign

    {
      "body": "string",
      "signature_submission_url": "string"
    }
    
    

    A message to be signed. The signature must be sent in the body of a POST request to the URL specified by "signature_submission_url".

    Properties

    Name Type Required Restrictions Description
    body string true none none
    signature_submission_url string true none none

    PlacedOrder

    {
      "id": "0123456789abcdefghijk",
      "payment_details": {
        "type": "crypto_address",
        "crypto_address": "0xf35074bbd0a9aee46f4ea137971feec024ab7048"
      },
      "input": {
        "currency": "ETH",
        "amount": "0.5",
        "type": "crypto_address",
        "crypto_address": "0x24305d091f79ee490a34de080b0db5773be5bef4"
      },
      "output": {
        "currency": "CHF",
        "amount": "104.95",
        "type": "bank_account",
        "iban": "CH3600000000000000000",
        "bic_swift": "BCNNCH22",
        "owner": {
          "name": "John Doe",
          "country": "CH",
          "city": "Neuchatel",
          "address": "Rue des Fahrys 2"
        }
      },
      "timestamp_created": "2019-01-24T13:14:07.368Z",
      "timestamp_cancelled": "2019-01-25T01:06:11.632Z",
      "legacy_status": "CANC"
    }
    
    

    Details of a previous placed order

    Properties

    Name Type Required Restrictions Description
    id string false none Unique ID of the order
    input PlacedOrderInputOutput true none none
    message_to_sign MessageToSign false none A message to be signed. The signature must be sent in the body of a POST request to the URL specified by "signature_submission_url".
    output PlacedOrderInputOutput true none none
    payment_details object false none none
    » type PlacedOrderInputOutputType false none none
    » crypto_address string false none Only valid if type is crypto_address.
    » account_number string false none none
    » bank_address string false none none
    » bank_code string false none none
    » iban string false none none
    » recipient string false none none
    » swift_bic string false none none
    timestamp_created string(date-time) true none In order for the order to be executed exactly as shown, the input must be paid within ten minutes of timestamp_created with a single transaction. If the amount is paid after the ten-minute window, the output amount might change during execution.
    timestamp_cancelled string(date-time) false none Date and time at which the order was cancelled.
    legacy_status string false none none

    Enumerated Values

    Property Value
    legacy_status OPEN
    legacy_status CANC
    legacy_status ERR
    legacy_status EXEC
    legacy_status PART
    legacy_status RFND

    PlacedOrderInputOutput

    {
      "input": {
        "currency": "ETH",
        "amount": "0.5",
        "type": "crypto_address",
        "crypto_address": "0x24305d091f79ee490a34de080b0db5773be5bef4"
      },
      "output": {
        "currency": "CHF",
        "amount": "104.95",
        "type": "bank_account",
        "iban": "CH3600000000000000000",
        "bic_swift": "BCNNCH22"
      }
    }
    
    

    Properties

    Name Type Required Restrictions Description
    amount string false none none
    currency CurrencyCode true none none
    type PlacedOrderInputOutputType true none none
    crypto_address string false none Only valid if type is crypto_address.
    iban string false none Only valid if type is bank_account.
    bic_swift string false none Only valid if type is bank_account.
    owner object false none Only valid if type is bank_account.
    » name string false none none
    » address string false none none
    » address_complement string false none none
    » zip string false none none
    » city string false none none
    » state string false none none
    » country string false none Must contain the two-letter country code (ISO 3166-1 alpha-2).

    PlacedOrderInputOutputType

    "crypto_address"
    
    

    Properties

    Name Type Required Restrictions Description
    anonymous string false none none

    Enumerated Values

    Property Value
    anonymous crypto_address
    anonymous bank_account