NAV Navbar
shell
  • Introduction
  • Currency pairs
  • Currencies
  • Estimating the amounts for an order
  • Placing an order with a phone number
  • Obtaining details of a previously placed order
  • Listing placed orders
  • Introduction

    API Endpoint

    https://bity.com/api/v2/
    

    The Bity API is organized around REST. Our API has predictable, resource-oriented URLs.

    All requests are assumed an user is logged in, unless specifically stated otherwise.

    Pagination of lists

    Unless specified in the documentation of an endpoint, results returned by the endpoints are not and can not be paginated.

    Encoding of amounts

    All amounts are encoded as the decimal representation inside a string. For instance "0.000012", "1234567.89" and "12" are valid amounts while 1 and 2.3 are not.

    Currency pairs

    Listing currency pairs

    Example request

    curl "https://bity.com/api/v2/pairs"
    
    {
      "pairs": [
        {"input": "BTC", "output": "CHF", "enabled": false},
        {"input": "BTC", "output": "ETH", "enabled": false},
        {"input": "BTC", "output": "EUR", "enabled": false},
        {"input": "BTC", "output": "REP", "enabled": false},
        {"input": "CHF", "output": "BTC", "enabled": true},
        {"input": "CHF", "output": "ETH", "enabled": true},
        {"input": "CHF", "output": "REP", "enabled": true},
        {"input": "ETH", "output": "BTC", "enabled": true},
        {"input": "ETH", "output": "CHF", "enabled": true},
        {"input": "ETH", "output": "EUR", "enabled": true},
        {"input": "ETH", "output": "REP", "enabled": true},
        {"input": "EUR", "output": "BTC", "enabled": true},
        {"input": "EUR", "output": "ETH", "enabled": true},
        {"input": "EUR", "output": "REP", "enabled": true}
      ]
    }
    

    You can get a list of all the currency pairs that can be traded through the Bity platform with the following request.

    GET /api/v2/pairs

    This endpoint does not require you to be logged in to the service.

    Filtering list of currency pairs

    Example request for filtering for multiple input currency codes

    curl "https://bity.com/api/v2/pairs?input=BTC&input=ETH"
    
    {
        "pairs": [
            {"enabled": true, "input": "BTC", "output": "CHF"},
            {"enabled": true, "input": "BTC", "output": "ETH"},
            {"enabled": true, "input": "BTC", "output": "EUR"},
            {"enabled": true, "input": "BTC", "output": "REP"},
            {"enabled": true, "input": "ETH", "output": "BTC"},
            {"enabled": true, "input": "ETH", "output": "CHF"},
            {"enabled": true, "input": "ETH", "output": "EUR"},
            {"enabled": true, "input": "ETH", "output": "REP"}
        ]
    }
    
    Filters Description
    input Retrieve all pairs for given input currency code
    output Retrieve all pairs for given output currency code
    enabled Retrieve all pairs that are enabled for trading or not

    Currencies

    Listing currencies

    Example request

    curl "https://bity.com/api/v2/currencies"
    
    {
      "currencies": [
        {"code": "BTC", "tags": ["crypto"]},
        {"code": "CHF", "tags": ["fiat"]},
        {"code": "ETH", "tags": ["crypto", "ethereum"]},
        {"code": "EUR", "tags": ["fiat"]},
        {"code": "REP", "tags": ["crypto", "ethereum", "erc20"]}
      ]
    }
    

    In order to get the supported currencies use the following endpoint.

    GET /api/v2/currencies

    This endpoint does not require you to be logged in to the service.

    Filtering list of currencies

    Filters Description
    tags Comma-separated list of tags. Currencies that contain all tags will be filtered.
    code Currency code to filter by. If specified multiple times all currencies matching the given codes will be filtered.

    Example request for filtering based on tag

    curl "https://bity.com/api/v2/currencies?tags=fiat"
    
    {
      "currencies": [
        {"code": "CHF", "tags": ["fiat"]},
        {"code": "EUR", "tags": ["fiat"]}
      ]
    }
    

    Example request for filtering based on code and sets of tags

    curl "http://localhost:8000/api/v2/currencies?code=EUR&code=BTC&tags=crypto,erc20"
    
    {
        "currencies": [
            {"code": "BTC", "tags": ["crypto"]},
            {"code": "EUR", "tags": ["fiat"]},
            {"code": "REP", "tags": ["crypto", "ethereum", "erc20"]}
        ]
    }
    
    Filters Description
    tags Filter results based on the tags of each currency. Multiple tags arguments can be provided and each instance can be a comma separated list of tags. A query such as tags=fiat&tags=crypto,erc20 will be evaluated as set(crypto, erc20) is subset of currency.tags OR set(fiat) in currency.tags
    code Filter results based on the code. Multiple codes can be provided.

    Estimating the amounts for an order

    The following endpoint allow an accurate estimation to be done for the output amount given an input amount and vice-versa. It however does not take into account all the limitations (such as currently consumed quota) that are enforced when an order is placed. As such, obtaining an estimation does not guarantee that the corresponding order can be placed.

    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.

    POST /api/v2/orders/estimate

    Estimate the output amount corresponding to an input amount

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

    Example: obtain the output amount in EUR for a given input amount in BTC

    curl -X POST \
      -H 'Content-Type: application/json' \
      -d '{"input": {"currency": "BTC", "amount": "0.91"}, "output": {"currency": "EUR"}}' \
      'https://bity.com/api/v2/orders/estimate'
    
    {
      "input": {
        "currency": "BTC",
        "amount": "0.91"
      },
      "output": {
        "currency": "EUR",
        "amount": "2693.20"
      }
    }
    

    Estimate the input amount corresponding to an output amount

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

    Example: obtain the input amount in BTC for a given output amount in CHF

    curl -X POST \
      -H 'Content-Type: application/json' \
      -d '{"input": {"currency": "BTC"}, "output": {"currency": "CHF", "amount": "100"}}' \
      'https://bity.com/api/v2/orders/estimate'
    
    {
      "input": {
        "currency": "BTC",
        "amount": "0.03038006586459039574926979233"
      },
      "output": {
        "currency": "CHF",
        "amount": "100"
      }
    }
    

    Placing an order with a phone number

    Placing orders with a phone number allows you to avoid having to create a Bity account and to go through KYC, but it has certain limitations.

    Establish a session

    Establishing a session is done in two steps:

    Request 1: submit the phone number

    POST /api/v2/login/phone

    The phone number given in the JSON body must be in the usual international format starting with a "+" and the country code.

    Example: submit the phone number

    curl -X POST \
      -H 'Content-Type: application/json' \
      -d '{"phone_number": "+410123456789"}' \
      'https://bity.com/api/v2/login/phone'
    

    Response 1: receive the phone token

    Example: response with the phone token

    {"phone_token": "example_phone_token"}
    

    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

    POST /api/v2/login/phone

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

    Example: submit the received sms code

    curl -X POST \
      -H 'Content-Type: application/json' \
      -H 'X-Phone-Token: example_phone_token' \
      -d '{"tan": "..."}' \
      'https://bity.com/api/v2/login/phone'
    

    Response 2

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

    Create the order

    Request

    POST /api/v2/orders/phone

    The request must include the X-Phone-Token header. The body of the request is as follows:

    Request body to create an order

    {
        "input": {
            "amount": "0.5",
            "currency": "ETH",
            "type": "crypto_address",
            "crypto_address": "0x..."
        },
        "output": {
            "currency": "CHF",
            "type": "bank_account",
            "iban": "...",
            "bic_swift": "...",
            "aba_number": "...",
            "sort_code": "...",
            "owner": {
                "name": "...",
                "address": "...",
                "address_complement": "...",
                "zip": "...",
                "city": "...",
                "state": "...",
                "country": "..."
            }
        }
    }
    

    The input or output amount can be estimated beforehand using the dedicated endpoint.

    Example: placing an order

    curl -X POST \
      -H 'Content-Type: application/json' \
      -H 'X-Phone-Token: example_phone_token' \
      -d '{
            "input": {
              "amount": "0.5",
              "currency": "ETH",
              "type": "crypto_address",
              "crypto_address": "0x..."
            },
            "output": {
              "currency": "CHF",
              "type": "bank_account",
              "iban": "CH3600000000000000000",
              "bic_swift": "CHAAAABBXXX"
              "owner": {
                "name": "Full name",
                "address": "Brückenstrasse 12",
                "address_complement": "",
                "zip": "3000",
                "city": "Bern",
                "state": "",
                "country": "CH"
              }
            }
          }' \
      'https://bity.com/api/v2/login/phone'
    

    Response

    In case the order is successfully placed, a 201 (created) response is returned. 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.

    Retrieving order details

    Request

    GET /api/v2/orders/:id

    The request must include the X-Phone-Token header.

    Example: retrieve the order details

    curl \
      -H 'X-Phone-Token: example_phone_token' \
      'https://bity.com/api/v2/orders/0123456789abcdefghijk'
    

    Response

    See Obtaining order details of a previously placed order .

    With this ordering method, the input object will always contain the information of the bank account or crypto address that must be used to pay the order.

    Listing previously placed orders

    Request

    GET /api/v2/orders

    The request must include the X-Phone-Token header.

    Example: retrieve the list of placed orders

    curl \
      -H 'X-Phone-Token: example_phone_token' \
      'https://bity.com/api/v2/orders'
    

    Response

    See Listing placed orders

    Obtaining details of a previously placed order

    The following endpoint can be used to obtain the details of a previously placed order:

    GET /api/v2/orders/:id

    {
        "id": "0123456789abcdefghijk",
        "payment_details": {
            "type": "crypto_address",
            "crypto_address": "0x..."
        },
        "input": {
            "currency": "ETH",
            "amount": "0.5",
            "type": "crypto_address",
            "crypto_address": "0x..."
        },
        "output": {
            "currency": "CHF",
            "amount": "104.95",
            "type": "bank_account",
            "iban": "..."
        },
        "timestamp_created": "...",
        "legacy_status": "OPEN"
    }
    

    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 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.

    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

    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.

    Example: Payment details when paying to a BTC address is required

    {
        "type": "crypto_address",
        "crypto_address": "2N2Y1PBdqiYMofgXid26Z4cQp1yC39h7Qti"
    }
    

    Bank account

    When the payment must be made to a bank account, the type is "bank_account" and the following information can be available:

    In most cases the bank sending the payment will only require to the IBAN, SWIFT code and maybe the recipient. However, in some cases the bank will ask for more so extra information is provided.

    Example: Payment details when paying to a bank account is required

    {
        "type": "bank_account",
        "account_number": "123456789",
        "bank_address": "Banque Cantonale Neuchâtelsoise\nPlace Pury 4\n2001 Neuchatel\nSwitzerland",
        "bank_code": "BCNNCH22XXX",
        "iban": "CH3600000000000000000",
        "recipient": "Bity SA\nRue des Usines 44\n2000 Neuchatel\nSwitzerland",
        "swift_bic": "123456"
    }
    

    Listing placed orders

    Previously placed orders can be listed using the following endpoint. Only orders linked to the currently authenticated entity will be shown.

    GET /api/v2/orders

    This endpoint can be used to:

    Example: list of orders response

    {
        "orders": [
           {
               "id": "0123456789abcdefghijk",
                   "payment_details": {
                       "type": "crypto_address",
                       "crypto_address": "0x..."
                   },
                   "input": {
                       "currency": "ETH",
                       "amount": "0.5",
                       "type": "crypto_address",
                       "crypto_address": "0x..."
                   },
                   "output": {
                       "currency": "CHF",
                       "amount": "104.95",
                       "type": "bank_account",
                       "iban": "..."
                   },
                   "timestamp_created": "...",
                   "legacy_status": "OPEN"
            },
            {
                ...
            }
        ]
    }