Skip to main content

Exchanging currencies

Overview​

The Strike API can be used to exchange different supported currencies, such as exchanging US dollars for bitcoin. This walkthrough shows you how to set up and execute currency exchanges within your Strike account.

How exchanging a currency works​

Exchanging currencies via the Strike API begins with creating an exchange quote. An exchange quote specifies which two currencies are to be exchanged and in what amount. When the exchange quote has been created, it will have an expiration time, as it offers a temporary exchange rate between the two currencies.

If the exchange rate is acceptable, the exchange quote can be executed prior to its expiration. Once executed, the currency exchange will take place within your Strike account, debiting the sold currency amount and crediting the bought currency amount.

Integration walkthrough​

1. Check for supported currencies​

You can exchange any currencies that are available to your Strike account. To check which currencies are available for a specific Strike user, you can use the fetch public account profile info by handle endpoint. If the Strike user’s profile is set to private, the endpoint will return 404.

Below is an example request to fetch public account profile info:

Example request:
curl -X 'GET' \
 'https://<ENVIRONMENT>/v1/accounts/handle/<HANDLE>/profile' \
 -H 'accept: application/json' \
 -H 'Authorization: Bearer <API_KEY>'

To use this example yourself, simply replace the placeholder values with your own values. The <ENVIRONMENT> should be replaced with api.strike.me, the <API_KEY> should be replaced with your own API key bearer token, and the <HANDLE> should be replaced with the relevant Strike handle.

Below is the response to the fetch public account profile info request:

Example response:
{
 "handle": "astrid_waters64",
 "canReceive": true,
 "currencies": [
   {
     "currency": "BTC",
     "isDefaultCurrency": false,
     "isAvailable": true,
     "isInvoiceable": true
   },
   {
     "currency": "USD",
     "isDefaultCurrency": true,
     "isAvailable": true,
     "isInvoiceable": true
   }
 ]
}

In the above response, both BTC and USD have isAvailable returned as true, indicating that those currencies are available for exchanging.

2. Create a currency exchange quote​

To create an exchange quote, use the create currency exchange quote endpoint. For this endpoint, you must specify your desired currencies to buy and sell, as well as an amount that you wish to exchange. The amount can be entered as either your buy or sell currency, depending if you wish to denominate the transaction as a specific amount to be bought or sold.

Below is an example request to create a quote for exchanging $5.00 USD for BTC:

Example request:
curl -L -X POST 'https://<ENVIRONMENT>/v1/currency-exchange-quotes' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <API_KEY>' \
--data-raw '{
  "sell": "USD",
  "buy": "BTC",
  "amount": {
    "amount": "5.00",
    "currency": "USD"
  }
}'

Below is the response to the exchange quote creation request:

Example response:
{
  "id": "6a3af0ed-ba86-44fc-a3be-1ea92696f331",
  "created": "2023-05-11T20:56:13.9259677+00:00",
  "validUntil": "2023-05-11T20:56:26.477+00:00",
  "source": {
    "amount": "5.00",
    "currency": "USD"
  },
  "target": {
    "amount": "0.000184",
    "currency": "BTC"
  },
  "conversionRate": {
    "amount": "0.0000368",
    "sourceCurrency": "USD",
    "targetCurrency": "BTC"
  },
  "state": "NEW"
}

The above response shows the newly created exchange quote, which is in the NEW state and is identifiable by its unique id. This exchange quote is for selling $5.00 USD in exchange for 0.000184 bitcoin (aka 18,400 sats), at the rate of 0.0000368 BTC per USD.

If the account does not have sufficient funds to execute the currency exchange, a 422 error will be returned.

If instead you wish the exchange to be quoted in a specific amount of currency to buy, such as a specific amount of bitcoin to acquire, you can follow the example exchange rate request below:

Example request:
curl -L -X POST 'https://<ENVIRONMENT>/v1/currency-exchange-quotes' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <API_KEY>' \
--data-raw '{
  "sell": "USD",
  "buy": "BTC",
  "amount": {
    "amount": "0.0001",
    "currency": "BTC"
  }
}'

Below is the response to the exchange quote creation request denominated in bitcoin:

Example response:
{
  "id": "6a3af0ed-ba86-44fc-a3be-1ea92696f331",
  "created": "2023-05-11T20:56:13.9259677+00:00",
  "validUntil": "2023-05-11T20:56:26.477+00:00",
  "source": {
    "amount": "2.71",
    "currency": "USD"
  },
  "target": {
    "amount": "0.0001",
    "currency": "BTC"
  },
  "conversionRate": {
    "amount": "0.0000369",
    "sourceCurrency": "USD",
    "targetCurrency": "BTC"
  },
  "state": "NEW"
}

The above response shows the exchange quote for $2.71 USD to buy the specified 0.0001 BTC.

3. Execute a currency exchange quote​

To complete the currency exchange, you must execute the quote. To execute the quote, use the currency exchange quote execute endpoint and specify the id of the quote that was returned in the quote creation response in step 2. Quotes must be executed prior to their expiration, which can be found in the quote’s validUntil timestamp. Please note that exchange quotes expire more quickly than payment quotes.

Below is an example request to execute a quote:

Example request:
curl -X 'PATCH' \
'https://<ENVIRONMENT>/v1/currency-exchange-quotes/<QUOTE_ID>/execute' \
 -H 'accept: application/json' \
 -H 'Authorization: Bearer <API_KEY>' \

When a quote is successfully executed, a 202 Accepted HTTP response status code will be returned, indicating that the currency exchange order has been successfully received and initiated within your account. Please note that a body response will not accompany the 202 Accepted code.

4. Check the status of a quote​

You can be notified of an exchange quote’s state change by subscribing to the currency-exchange-quote.updated webhook event. When one of your subscribed events occurs, a POST request will be automatically made to the webhook URI of the subscription. For details on how to subscribe to webhook events visit the webhooks section.

Below is an example webhook subscription response for the currency-exchange-quote.updated webhook event:

Example response:
{
  "id": "34f43981-fe06-4d05-9fc4-e858e8f9529b4",
  "eventType": "currency-exchange-quote.updated",
  "webhookVersion": "v1",
  "data": {
    "entityId": "11aa533f-232b-5bff-b967-abba2beef13",
    "changes": [
      "state"
    ]
  },
  "created": "2023-02-03T03:34:34+00:00",
}

In this response, the id is the webhook event ID and the entityId is the ID of the currency exchange quote, indicating that the state of the quote has changed. Please note that the webhook subscription response doesn’t contain the quote’s state, rather it describes that the state has changed.

To request the new state of the quote, use the get currency exchange quote endpoint.

Below is an example request to get a currency exchange quote:

Example request:
curl -X 'GET' \
 'https://<ENVIRONMENT>/v1/currency-exchange-quotes/<QUOTE_ID>' \
 -H 'accept: application/json' \
 -H 'Authorization: Bearer <API_KEY>'

Below is the response to the get currency exchange quote:

Example response:
{
  "id": "6a3af0ed-ba86-44fc-a3be-1ea92696f331",
  "created": "2023-05-11T20:56:13.925967+00:00",
  "validUntil": "2023-05-11T20:56:26.477+00:00",
  "source": {
    "amount": "5.00",
    "currency": "USD"
  },
  "target": {
    "amount": "0.000184",
    "currency": "BTC"
  },
  "conversionRate": {
    "amount": "0.0000368",
    "sourceCurrency": "USD",
    "targetCurrency": "BTC"
  },
  "state": "COMPLETED",
  "completed": "2023-05-11T20:56:24.295406+00:00"
}

For the above example, the quote was executed successfully as indicated by the state having transitioned to COMPLETED at the corresponding completed timestamp. $5.00 USD was debited from the user’s dollar balance and 0.000184 BTC was credited to their bitcoin balance ($5 of bitcoin was purchased).