Buying Cryptocurrencies

All trading of cryptocurrencies in the Safello APIs is carried out via "Orders" - either Buy Orders as documented here, or Sell Orders as documented on the page for selling Cryptocurrencies.

To buy some cryptocurrency a buy order must be created. This will represent the lifecycle of the trade as it is recorded in the Safello system, fiat funds are received to pay for the trade, the trade is executed, the cryptocurrency is recorded to the customer's credit, and so on.

Creating a Buy Order

A buy order is created by making a POST request to the /v2/orders/buy endpoint with a payload specifying the desired cryptocurrency, fiat value of that currency to purchase, and the payment mechanism along with any necessary supplementary information.

For example, a customer can purchase 350 SEK (fiat value) of BTC (crypto currency) using bankgiro (payment method)

Creating a buy order example

curl \
   --verbose --silent \
   --header "Authorization: Bearer $ACCESS_TOKEN" \
   --header 'source-ip-address: 127.0.0.1' \
   --header 'source-user-agent: curl' \
   --header 'Content-Type: application/json' \
   --request POST \
   --location 'https://api.s4f3.io/v2/orders/buy' \
   --data '{ "cryptoCurrency": "BTC", "fiat": { "currency": "SEK", "amount": "350.00" }, "paymentMethod": "bankgiro" }'

tip

At the present time the minimum purchase amount for a buy order is 350 SEK. In some special cases it is possible for Safello to create smaller buy orders using an alternate mechanism.

The response to the successful creation of a Buy Order will include an order identifier string.

{
  "orderId": "TQ2OKMN",
  "pollingUrl": "https://api.s4f3.io/v2/orders/TQ2OKMN"
}

This identifier (in the given example this is TQ2OKMN) should then be used to track the status and any future information about the order.

Retrieving buy order details

The created buy order's identifier may be passed as a path parameter in a GET request to the /v2/orders/{orderId} endpoint in order to determine the buy order's current status and details. Note that this URL will also correspond exactly to the value of the pollingUrl field returned within the response payload of the buy order creation endpoint.

Checking the buy order details example

In this example the created buy order's identifier is TQ2OKMN and thus used in composing the query URL.

curl \
   --verbose --silent \
   --header "Authorization: Bearer $ACCESS_TOKEN" \
   --header 'source-ip-address: 127.0.0.1' \
   --header 'source-user-agent: curl' \
   --request GET \
   --location 'https://api.s4f3.io/v2/orders/TQ2OKMN'

note

The same endpoint (qualified by the order ID) is used for both Buy and Sell orders, although different fields will be populated depending upon the type of the order.

As well as the values included when creating the buy order, the details will include the fees and the current status of the buy order.

{
  "id": "TQ2OKMN",
  "created": "2022-05-10T14:36:59Z",
  "fiat": {
    "currency": "SEK",
    "amount": "350.00"
  },
  "crypto": {
    "currency": "BTC",
    "amount": "0.00339998"
  },
  "feeRate": "0.0500",
  "fee": {
    "currency": "SEK",
    "amount": "35.00"
  },
  "receivedCrypto": null,
  "sold": null,
  "payout": null,
  "status": "completed",
  "type": "buy",
  "paymentMethod": "bankgiro"
}

In the given example the buy order status is completed so the purchased cryptocurrency will be in the customer's wallet.

Listing all order details

As an alternative to listing an individual buy order, it is possible to retrieve all orders for a customer. These will include both buy orders and sell orders. You should also note that buy and sell orders created outside of the institutional API (for example by using the Safello app) may be included in the returned results.

To list all of a customer's order details, make a GET request to the /v2/orders endpoint

Listing all order details example

warning

At the time of writing (2022-05-10) there is a bug in the path handling on this endpoint - you must include the trailing slash / with your request or the response will be a 404 "not found".

curl \
   --verbose --silent \
   --header "Authorization: Bearer $ACCESS_TOKEN" \
   --header 'source-ip-address: 127.0.0.1' \
   --header 'source-user-agent: curl' \
   --header 'Content-Type: application/json' \
   --request GET \
   --location 'https://api.s4f3.io/v2/orders/'

Note that this endpoint uses pagination as it is capable of generating very long lists of results. If no offset is explicitly specified then the first page of results (equivalent to setting an offset query parameter of zero) is returned.

{
  "offset": 0,
  "size": 1,
  "total": 1,
  "data": [
    {
      "id": "TQ2OKMN",
      "created": "2022-05-10T14:36:59Z",
      "fiat": {
        "currency": "SEK",
        "amount": "350.00"
      },
      "crypto": {
        "currency": "BTC",
        "amount": "0.00339998"
      },
      "feeRate": "0.0500",
      "fee": {
        "currency": "SEK",
        "amount": "35.00"
      },
      "receivedCrypto": null,
      "sold": null,
      "payout": null,
      "status": "completed",
      "type": "buy",
      "paymentMethod": "bankgiro"
    }
  ]
}

The data returned from the endpoint will contain the same entries as would be received if you queried the status directly for each of the orders in question.