NAV Navbar
shell
  • Introduction
  • Authentication
  • Errors
  • Handling list results
  • Users
  • Rates
  • Orders
  • Introduction

    API Endpoint

    https://bity.com/api/v1/
    

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

    Most requests are from the perspective of the currently logged in user.

    Authentication

    Bity's API uses standard OAuth tokens. The user requests a token from the server before using the API. The token is used via the Authorization header in all subsequent requests.

    Authorization: Bearer 0UDvVV9qitGkoGPHOzFzJDBurlbGomU

    Errors

    Whenever an error occurs a JSON body is sent containing an error_code and error_description property.

    Example of a returned error body with 401 code

    {
      "error_description": "Invalid credentials given.",
      "error": "invalid_grant"
    }
    

    error_description should only be used as a crude way to report errors to people. It's understood for many applications it will be sufficient. Even then we suggest using error combined with i18n translations for better presentation.

    Bity's API uses the following error codes in its responses:

    Error Code Meaning
    400 Bad Request -- Your request is invalid.
    401 Unauthorized -- Your API token is invalid or has expired.
    403 Forbidden -- The resource is protected and cannot be accessed.
    404 Not Found -- The requested resource could not be found.
    500 Internal Server Error -- We had a problem with our server. Try again later.

    Handling list results

    In Bity's API whenever a list of objects is returned there will be a meta sub-object that will contain information about the pagination and objects list with the results.

    You can manipulate the limit and offset parameters in the original request so that you retrieve the list according to your needs.

    Example of a request with up to 10 elements per page and offset 1

    curl --dump-header - \
    -H "Authorization: Bearer ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    "https://bity.com/api/v1/<RESOURCE_PATH>/?limit=10&offset=1"
    

    Example response

    {
      "meta": {
        "limit": 10,
        "next": "/api/v1/<RESOURCE_PATH>/?limit=10&offset=1",
        "offset": 1,
        "previous": "/api/v1/<RESOURCE_PATH>/?offset=0&limit=10",
        "total_count": 47
      },
      "objects": [
        {...},
        {...},
        {...},
        {...},
        {...},
        {...},
        {...},
        ......... up to 10
      ]
    }
    

    meta object

    Attribute Editable Description
    limit Yes The maximum number of entries to return per page. Defaults to 5.
    next No URL path to the next page, or null if there are no more pages.
    offset Yes Current page, starting at 0.
    previous No URL path to the previous page, or null if the current page is 0.
    total_count No Total number of elements in the list.

    Sorting lists

    You can sort lists by a given attribute of the response objects. To do so simply specify order_by= in the query string followed by either - (descending order) or + (ascending order) and the name of the attribute.

    Example request for sorting by id ascending

    curl --dump-header - \
    -H "Authorization: Bearer ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    "https://bity.com/api/v1/<RESOURCE_PATH>/?order_by=+id"
    

    Example response

    {
      "meta": {
        "limit": 5,
        "next": null,
        "offset": 0,
        "previous": null,
        "total_count": 3
      },
      "objects": [
        {
          "id": 1,
          ...
        },
        {
          "id": 2,
          ...
        },
        {
          "id": 3,
          ...
        }
      ]
    }
    

    Users

    Sign up

    Right now the only way to sign up is manually through Bity's webpage

    User activation

    Upon signing up a registration code will be sent to the provided phone number. That code must be provided in order to activate the user and allow him to keep interacting with the system.

    Example request to activate a user with the received code by SMS

    curl -k --dump-header - \
    -H "Content-Type: application/json" \
    -X POST \
    --data '{"phone": "+41786399501", "code": "381499"}' \
    "https://bity.com/api/v1/user_signup/verifyphone/"
    

    Example response if the user has been successfully activated

    {
      "activated": true
    }
    

    Request

    POST /user_signup/verifyphone/

    Request body (JSON)

    Parameter Description
    phone User's phone number in international format. The "+" must be included.
    code Received code by SMS.

    Log in

    Example request to log in

    curl -k --dump-header - \
    -X POST \
    --data 'grant_type=password&username=%2B41786399501&password=abc123&client_id=QmaTkYI50XmCF18fupZgdAOptYqDzVix12RpqFYS' \
    "https://bity.com/o/token/"
    

    Example response if the user succeeded to log in

    {
      "access_token": "2VUlB6JDQbHu8S9qwBfOU7Ghm1eDva",
      "token_type": "Bearer",
      "expires_in": 36000,
      "refresh_token": "ixA3CVNRUMGpqvePOEGCDkA7LxyuiA",
      "scope": "read write"
    }
    

    Example response if the user failed to log in

    {
      "error_description": "Invalid credentials given.",
      "error": "invalid_grant"
    }
    

    HTTP Request

    POST /o/token/

    Request body

    Parameter Description
    username Username. No spaces allowed. It can be the user's phone, email or actual username used when signing up.
    password User's password in plain text.
    grant_type Authentication method. It should be "password".
    client_id This client's unique ID.

    Rates

    This resource allows you to retrieve Bity's exchange rates for a two given currencies.

    You can find in the table below the different allowed currencies:

    Name Code Type Allowed operations
    Euro EUR FIAT Buy / Sell
    Swiss Francs CHF FIAT Buy / Sell
    Bitcoin BTC CRYPTO Buy / Sell
    Ether ETH CRYPTO Buy / Sell
    Augur REP CRYPTO Sell

    All rates

    Example request to get all rates

    curl "https://bity.com/api/v1/rate2/"
    
    {
      "meta": {
        "disabled": "USDUSD",
        "limit": 20,
        "next": null,
        "offset": 0,
        "previous": null,
        "total_count": 32
      },
      "objects": [
        {
          "is_enabled": true,
          "pair": "ETHEUR",
          "rate": "452.40000000",
          "rate_we_buy": "449.91370000",
          "rate_we_buy_timestamp": "2018-06-20T10:28:05.718739",
          "rate_we_sell": "456.44620000",
          "rate_we_sell_timestamp": "2018-06-20T10:28:04.657892",
          "resource_uri": "/api/v1/rate2/ETHEUR/",
          "source": "ETH",
          "target": "EUR",
          "timestamp": "2018-06-20T10:28:03.484648"
        },
        {
          "is_enabled": true,
          "pair": "ETHCHF",
          "rate": "521.56700000",
          "rate_we_buy": "514.20140000",
          "rate_we_buy_timestamp": "2018-06-20T10:28:06.124509",
          "rate_we_sell": "530.79630000",
          "rate_we_sell_timestamp": "2018-06-20T10:28:05.092754",
          "resource_uri": "/api/v1/rate2/ETHCHF/",
          "source": "ETH",
          "target": "CHF",
          "timestamp": "2018-06-20T10:28:03.969629"
        },
        ...
      ]
    }
    

    HTTP Request

    GET /rate2/

    Price we sell

    Example request to get the BTC/ETH rate

    curl "https://bity.com/api/v1/rate_we_sell/ETHBTC/"
    

    Example response

    {
      "pair": "ETHBTC",
      "rate": "0.06714700",
      "resource_uri": "/api/v1/rate_we_sell/ETHBTC/",
      "source": "ETH",
      "target": "BTC",
      "timestamp": "2018-04-19T11:41:05.078271"
    }
    

    HTTP Request

    GET /rate_we_sell/{CURRENCY_PAIR}/

    URL parameters

    Parameter Description
    CURRENCY_PAIR See here the complete list of allowed currencies.

    Price we buy

    Example request

    curl "https://bity.com/api/v1/rate_we_buy/ETHBTC/"
    

    Example response

    {
      "pair": "ETHBTC",
      "rate": "0.06664200",
      "resource_uri": "/api/v1/rate_we_buy/ETHBTC/",
      "source": "ETH",
      "target": "BTC",
      "timestamp": "2018-04-20T09:22:06.120138"
    }
    

    HTTP Request

    GET /rate_we_buy/{CURRENCY_PAIR}/

    URL parameters

    Parameter Description
    CURRENCY_PAIR See here the complete list of allowed currencies.

    Orders

    Create an order

    Example request to create an order from BTC to CHF (amount in CHF)

    curl --dump-header - \
    -H "Authorization: Bearer ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -X POST \
    --data '{"payment_method": "STRAIGHT", "currency": "", "amount": "AMOUNT_BTC", "amount_mode": 3, "crypto_address": "ETHER ADDRESS", "category":"BUY_ETH", "person": "/api/v1/person/PERSONID/"}' \
    "https://bity.com/api/v1/order/"
    

    Example response of the created order

    {
      "amount": "AMOUNT_BTC",
      "category": "BUY_ETH",
      "crypto_address": "ETHER ADDRESS",
      "currency": "",
      "inputtransactions": [
        {
          "amount": "AMOUNT_BTC",
          "currency": "BTC",
          "order": "/api/v1/order/ORDER_NUMBER/",
          "payment_method": "/api/v1/payment_method/STRAIGHT/",
          "payment_processor_fee": "0E-8",
          "reference": "BITYXXXXXX",
          "resource_uri": "/api/v1/input_transaction/INPUT_NUMBER/",
          "status": "OPEN"
        }
      ],
      "outputtransactions": [
        {
          "amount": "AMOUNT_ETH",
          "currency": "ETH",
          "order": "/api/v1/order/ORDER_NUMBER/",
          "payout_method": "/api/v1/payout_method/ETH/",
          "reference": "",
          "resource_uri": "/api/v1/output_transaction/OUTPUT_NUMBER/",
          "status": "OPEN"
        }
      ],
      "payment_amount": "AMOUNT_BTC",
      "payment_method": "STRAIGHT",
      "payment_url": "DESTINATION_BTC_ADDRESS",
      "person": "/api/v1/person/PERSONID/",
      "reference": "BITYXXXXXX",
      "resource_uri": "/api/v1/order/ORDER_NUMBER/",
      "status": "OPEN",
      "timestamp_created": "2016-06-12T21:50:12.367764",
      "unique_id": "69a2f7b4ede8499faf619dde0a5974e6"
    }
    

    HTTP Request

    POST /order/

    Request body

    Parameter Description
    payment_method Type of deposit. See payment methods.
    currency See the available currencies. The currency BTC can be omitted.
    amount The order's amount as a string. Maximum eight decimal digits.
    amount_mode See summary.
    crypto_address The client's cryptowallet address as a string.
    category A parameter indicating wether you want to buy or sell. See order summary.
    person Resource URL to the person creating the order. If left blank the first person associated to the account will be used.

    Order summary

    Pair Category Currency Payment code Amount mode (maps to)
    BTCCHF SELL CHF BTCGATEWAY* input*/output (input: AMOUNT_MODE_INPUT, output:AMOUNT_MODE_DEFAULT)
    BTCEUR SELL EUR BTCGATEWAY* input*/output (input: AMOUNT_MODE_INPUT, output:AMOUNT_MODE_DEFAULT)
    BTCETH BUY_ETH empty string BTCGATEWAY* input*/output (input: AMOUNT_MODE_DEFAULT, output:AMOUNT_MODE_OUTPUT)
    BTCREP BUY_REP empty string BTCGATEWAY* input*/output (input: AMOUNT_MODE_DEFAULT, output:AMOUNT_MODE_OUTPUT)
    CHFBTC BUY CHF BANKXFER, SOFORTPSP input* (input: AMOUNT_MODE_DEFAULT)
    CHFETH BUY_ETH CHF BANKXFER, SOFORTPSP input* (input: AMOUNT_MODE_DEFAULT)
    CHFREP BUY_REP CHF BANKXFER, SOFORTPSP input* (input: AMOUNT_MODE_DEFAULT)
    ETHBTC SELL_ETH empty string ETHGATEWAY* input*/output (input: AMOUNT_MODE_INPUT, output:AMOUNT_MODE_OUTPUT)
    ETHCHF SELL_ETH CHF ETHGATEWAY* input*/output (input: AMOUNT_MODE_INPUT, output:AMOUNT_MODE_DEFAULT)
    ETHEUR SELL_ETH EUR ETHGATEWAY* input*/output (input: AMOUNT_MODE_INPUT, output:AMOUNT_MODE_DEFAULT)
    ETHREP SELL_ETH REP ETHGATEWAY* input*/output (input: AMOUNT_MODE_INPUT, output:AMOUNT_MODE_OUTPUT)
    EURBTC BUY EUR BANKXFER, SOFORTPSP input* (input: AMOUNT_MODE_DEFAULT)
    EURETH BUY_ETH EUR BANKXFER, SOFORTPSP input* (input: AMOUNT_MODE_DEFAULT)
    EURREP BUY_REP EUR BANKXFER, SOFORTPSP input* (input: AMOUNT_MODE_DEFAULT)

    *: default (can be omitted)

    Payment methods

    Parameter Description Status
    BTCGATEWAY Pay with Bitcoin Active
    ETHGATEWAY Pay with Ether Active
    SOFORTPSP Pay with fiat currencies via Sofort Active
    SKRILLPSP Pay with fiat currencies via Skrill Deprecated
    STRAIGHT Pay with Bitcoin Deprecated

    Input handling modes

    Value Parameter Description
    0 EXACT Requires the input to be exactly the ordered amount.
    1 ANY_INPUT_0CONF Deprecated. Do not use this option.
    2 APPROXIMATE Recalculates the order automatically if the input is approximately the ordered amount.

    Amount mode

    Value Parameter Description
    0 AMOUNT_MODE_DEFAULT For BUY and BUY_ETH, the amount is the input amount (in FIAT currency or BTC). For SELL and SELL_ETH, the amount is the output amount (in FIAT currency).
    1 AMOUNT_MODE_INPUT In this mode, you specify the amount for input explicitly. For example, for SELL, you can specify the amount in BTC (input), which isn't possible in the "implicit mode" (AMOUNT_MODE_DEFAULT).
    2 AMOUNT_MODE_OUTPUT In this mode, you specify the amount for output explicitly. For example, for BUY_ETH, we can specify the amount for ETH (output), which isn't possible in the "implicit mode" (AMOUNT_MODE_DEFAULT).
    3 AMOUNT_MODE_INPUT_PLACEHOLDER In this mode, you can specify an amount as a placeholder, with the real value to be filled later (both input amount and output amount will be updated) when the payment is received. Right now, this mode is only supported in workflow BUY_ETH with BTC, and the account must be trusted (the param amount is referencing the BTC input).

    Retrieve all orders

    Example request to retrieve all orders

    curl --dump-header - \
    -H "Authorization: Bearer ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    "https://bity.com/api/v1/order/?order_by=-timestamp_created"
    

    Example response for retrieving all orders

    {
      "meta": {
        "limit": 5,
        "next": null,
        "offset": 0,
        "previous": null,
        "total_count": 2
      },
      "objects": [
        {
          "category": "BUY",
          "inputtransactions": [
            {
              "amount": "1200.00000000",
              "currency": "EUR",
              "order": "/api/v1/order/456321/",
              "payment_method": "/api/v1/payment_method/BANKXFER/",
              "payment_processor_fee": "0E-8",
              "reference": "bity.com U78M-00E2",
              "resource_uri": "/api/v1/input_transaction/345621/",
              "status": "CONF"
            }
          ],
          "outputtransactions": [
            {
              "amount": "0.17578666",
              "currency": "BTC",
              "order": "/api/v1/order/456321/",
              "payout_method": "/api/v1/payout_method/BTC/",
              "reference": "d5ac644a74bce69a2b47663e59274f844de37a4279e362f0b61e791729a736f0",
              "resource_uri": "/api/v1/output_transaction/5645645/",
              "status": "FILL"
            }
          ],
          "person": "/api/v1/person/151515/",
          "resource_uri": "/api/v1/order/179150/",
          "status": "EXEC",
          "timestamp_created": "2018-02-10T16:11:45.410543"
        },
        {
          "category": "BUY",
          "inputtransactions": [
            {
              "amount": "500.00000000",
              "currency": "EUR",
              "order": "/api/v1/order/3212123/",
              "payment_method": "/api/v1/payment_method/BANKXFER/",
              "payment_processor_fee": "0E-8",
              "reference": "bity.com HG89-09CX",
              "resource_uri": "/api/v1/input_transaction/43234324/",
              "status": "CONF"
            }
          ],
          "outputtransactions": [
            {
              "amount": "0.08031053",
              "currency": "BTC",
              "order": "/api/v1/order/3212123/",
              "payout_method": "/api/v1/payout_method/BTC/",
              "reference": "4b88a3290db72e4c82ce5f9691beda76132463461f0e454f841d2a7467fc792c",
              "resource_uri": "/api/v1/output_transaction/213123/",
              "status": "FILL"
            }
          ],
          "person": "/api/v1/person/877878/",
          "resource_uri": "/api/v1/order/3212123/",
          "status": "EXEC",
          "timestamp_created": "2018-04-01T16:47:54.656158"
        }
      ]
    }
    

    HTTP Request

    GET /order/