Skip to main content

Selling Cryptocurrencies

As with purchasing cryptocurrency, selling cryptocurrency requires the creation of an order - in this case a Sell Order. The sell order details what to sell and includes the destination for the funds resulting from the sale. A sell order cannot be placed for more funds than the customer holds in their wallet for the relevant cryptocurrency.

Sell Order state transitions

Establishing customer bank details​

In order to complete a sell order, the customer needs somewhere for the fiat funds from the sale to be deposited. An API is therefore provided to allow a bank account from the institution to be associated with the customer.

To associate a bank account with the customer, make a PUT request to the /v2/account/bank-account endpoint. The payload must include the account number, clearing number, and currency associated with the account and where possible should contain the appropriate user-friendly name of the account.

Create a customer bank account association example
curl \
   --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 PUT \
   --location 'https://api.s4f3.io/v2/account/bank-account' \
   --data '{ "name": "Savings", "accountNumber": "50011100011", "clearingNumber": "1234", "currency": "SEK" }'

The value of the id field in the response will then be used when creating sell orders to identify the destination of the funds of the sale.

{
  "default":true,
  "id":"f3f9eec1-885b-4053-82bb-d3c078d0fa60",
  "name":"Savings",
  "accountNumber":"50011100011",
  "clearingNumber":"1234",
  "currency":"SEK",
  "bank":"Avanza"
}

This endpoint is idempotent (multiple invocations will have no further effect and the response will always be the same) with the intention that the institution may invoke it whenever a customer is about to create a sell order in order to obtain or create the corresponding Safello identifier for use in the sell order payload. Alternatively if the institution has previously supplied bank account details for the customer an endpoint is supplied to list the customer's bank accounts.

Creating a Sell Order​

Creating a sell order is very similar to creating a buy order. A POST is made to the /v2/orders/sell endpoint with a payload detailing the fiat currency for which the cryptocurrency will be sold, the cryptocurrency type and amount to sell, and the bank account identifier to which the fiat funds will be sent upon completion of the trade. 

curl \
   --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/sell' \
   --data '{ "fiatCurrency": "SEK", "crypto": { "currency": "BTC", "amount": "0.0005" }, "bankAccountId": "f3f9eec1-885b-4053-82bb-d3c078d0fa60" }'
{
  "orderId": "Y8V9ICH",
  "pollingUrl":"https://api.s4f3.io/v2/orders/Y8V9ICH"
}

As with the buy order the result of the operation is the orderId field's value that can then be used to retrieve order details as in the endpoint indicated by the pollingUrl field's value.

Retrieving sell order details​

The mechanism for retrieving sell order details is identical to that for retrieving buy order details as the same endpoint is used. They differ only in the order ID passed in the path and the exact fields that will be populated in the response.

Listing all order details​

Both buy and sell orders are included when listing all order details, so see the corresponding section in the Buying Cryptocurrencies page for details.