API

Method Reference

In general, the flow is as follows:

  • You would use /coins to find available coins.
  • You would use /pairs to find pairs which contain the coin you want. (Or you would just query /pairs for a list of all pairs.)
  • You would use /rate to get the rate and limits for a specific pair that the user selected.
  • You would use /order to create an order on the user's behalf.
  • You would use /order/:orderId to query the order status.
    • In case of incomplete payment, you may offer the user to proceed with the lower amount, in which case you would call /order/:orderId/acceptPartial.

Additionally, there is /orders which can be used to get all the orders that you previously created.

Base URL for all the endpoints is https://fox.exchange/api/cs.

GET /coins

Get a list of all supported coins.

This endpoint is used to retrieve all currencies supported by fox.exchange.

In the response note that isActive may be temporarily false if a coin is unavailable. Also, for each coin a property unavailableInUserRegion: true may be returned in case this coin cannot be traded in the user's region.

Example:

$ curl -XGET 'https://fox.exchange/api/cs/coins' \
  -H 'x-api-key: DEADBEEFDEADBEEF' \
  -H 'x-user-ip: 127.0.0.1'

{
  "success": true,
  "code": "ok",
  "data": [
    {
      "name": "Bitcoin",
      "symbol": "BTC",
      "isActive": true,
      "isFiat": false,
      "icon": "https://fox.exchange/images/btc.svg"
    },
    {
      "name": "Ethereum",
      "symbol": "ETH",
      "isActive": true,
      "isFiat": false,
      "icon": "https://fox.exchange/images/eth.svg"
    },
    {
      "name": "Litecoin",
      "symbol": "LTC",
      "isActive": true,
      "isFiat": false,
      "icon": "https://fox.exchange/images/ltc.svg"
    },
    {
      "name": "Dash",
      "symbol": "DASH",
      "isActive": true,
      "isFiat": false,
      "icon": "https://fox.exchange/images/dash.svg"
    }
  ]
}

POST /pairs

Get exchange pairs for a chosen depositCoin or destinationCoin, or all pairs.

This endpoint is used to retrieve the exchange pairs supported by fox.exchange.

Body parameters:

  • depositCoin (optional): Coin symbol the user wants to convert from
  • destinationCoin (optional): Coin symbol the user wants to convert to

You can use this endpoint in three ways:

  • If you want to see which coins we can convert your chosen depositCoin to - specify your chosen depositCoin in the body.
  • If you want to see which coins can be converted to your chosen destinationCoin - specify your chosen destinationCoin in the body.
  • To see all pairs we support - specify neither depositCoin not destinationCoin in the body.

In the response note that isActive may be temporarily false if a pair is unavailable. Also, for each pair a property unavailableInUserRegion: true may be returned in case this pair cannot be traded in the user's region.

Example:

$ curl -XPOST 'https://fox.exchange/api/cs/pairs' \
  -H 'x-api-key: DEADBEEFDEADBEEF' \
  -H 'x-user-ip: 127.0.0.1' \
  -H 'Content-Type: application/json' \
  -d '{ \
        "depositCoin": "ETH" \
      }'

{
  "success": true,
  "code": "ok",
  "data": [
    {
      "depositCoin": "ETH",
      "destinationCoin": "BTC",
      "isActive": true
    },
    {
      "depositCoin": "ETH",
      "destinationCoin": "LTC",
      "isActive": true
    }
  ]
}

POST /rate

Generate an exchange offer for for a coin pair.

This endpoint will return the typical exchange rate fox.exchange can offer for your chosen coin pair, or a specific destination amount based on a deposit amount, as well as minimum and maximum amounts.

By default, an estimated rate offer is returned. fox.exchange may also offer a fixed rate. To use the fixed rate feature, send "requestFixed": true in the /rate call. If fixed rate is supported for the requested parameters, then the response will include a quoteToken and a validTill timestamp. To get the advertised rate, include the quoteToken in the following /order call and make sure the deposit is made in time.

Body parameters:

  • depositCoin: Coin symbol the user wants to convert from
  • destinationCoin: Coin symbol the user wants to convert to
  • depositCoinAmount (optional): Amount (in deposit currency) which the user wants to convert
  • requestFixed (optional): If set to true, Fox will return a fixed rate offer if available, instead of an estimated rate offer

Response fields:

  • rate: Effective rate
    • If a depositCoinAmount was specified, this is the rate for the given amount. In case the amount was invalid, the rate will be null.
    • If no depositCoinAmount was specified, this is the typical rate.
  • destinationCoinAmount: If an amount was specified, this is the expected amount the user would receive, otherwise this value is null
  • limitMinDepositCoin: Minimum amount possible to exchange
  • limitMaxDepositCoin: Maximum amount possible to exchange
  • futureOrderId: Can be used to know order ID in advance (does not lock price!)
  • quoteToken: If a fixed rate was requested and available, this token can be used to lock the rate that was returned (by passing it into the order creation endpoint)
  • validTill: If a fixed rate was requested and available, this is its expiration time (as ms-since-epoch timestamp) - deposit must be completed until that time

Note: Unless a fixed rate offer was returned (quoteToken exists), the displayed rate and destination amounts are approximate and not final. The final amount may slightly differ due to market fluctuations.

Example:

$ curl -XPOST 'https://fox.exchange/api/cs/rate' \
  -H 'x-api-key: DEADBEEFDEADBEEF' \
  -H 'x-user-ip: 127.0.0.1' \
  -H 'Content-Type: application/json' \
  -d '{ \
        "depositCoin": "BTC", \
        "destinationCoin": "ETH", \
        "depositCoinAmount": 0.005 \
      }'

{
  "success": true,
  "code": "ok",
  "data": {
    "rate": 40.17497089879646,
    "destinationCoinAmount": 0.2008748544939823,
    "limitMinDepositCoin": 0.001,
    "limitMaxDepositCoin": 0.35,
    "futureOrderId": "f6491f93dea2bea3db0bc6e76815912a6ace81d9f3a69c7d7d2cdbce28123c09"
  }
}

POST /order

Create an Order.

This endpoint creates a new transaction. It will return a simplified transaction object with the information required for the user to deposit their funds.

Body parameters:

  • depositCoin: Coin symbol the user wants to convert from
  • destinationCoin: Coin symbol the user wants to convert to
  • depositCoinAmount: Amount (in deposit currency) which the user wants to convert
  • destinationAddress: Wallet the user wants the exchanged coins to be sent to. This is an object containing the following properties:
    • address: Wallet address
    • tag: Payment ID or similar secondary identifier (only required for certain currencies)
  • userEmail (optional): User's email address - the user will receive updates to their transaction via email and will be able to visit the transaction status page
  • futureOrderId (optional): The ID returned in the /rate call - will become the order ID if passed
  • quoteToken (optional): The quote token returned in the /rate call - will ensure that the fixed rate is used that was given previously (will return a invalid_quote_token error if the token was expired or already used!) - must match the given coins and amount

Note: If you are using the application/x-www-form-urlencoded format, you of course cannot specify an object as destinationAddress. In that case, the sent string will be interpreted as address, and it's not possible to set a tag.

Response fields:

  • orderId: Order ID
  • exchangeAddress: The wallet the user has to send their funds to - this is an object containing the following properties:
    • address: Wallet address
    • tag: Payment ID or similar secondary identifier (only required for certain currencies)
  • qrCodeUrl: URL to a QR code image which the user can use to initiate the payment from a mobile wallet
  • expectedDepositCoinAmount: The amount the user has to deposit
  • expectedDestinationCoinAmount: Estimated amount the user will receive at the end
  • validTill: The order is valid until this time (given as ms-since-epoch timestamp), any payment submitted afterwards will not be recognized
  • frontendTimeout: The frontend deposit timer will run out at this time (given as ms-since-epoch timestamp), however payment is still recognized if sent afterwards

Note: Unless a fixed rate offer was used (quoteToken was sent), the displayed rate and destination amounts are approximate and not final. The final amount may slightly differ due to market fluctuations.

Example:

$ curl -XPOST 'https://fox.exchange/api/cs/order' \
  -H 'x-api-key: DEADBEEFDEADBEEF' \
  -H 'x-user-ip: 127.0.0.1' \
  -H 'Content-Type: application/json' \
  -d '{ \
        "depositCoin": "BTC", \
        "destinationCoin": "ETH", \
        "depositCoinAmount": 0.005 \
        "destinationAddress": { \
          "address": "0xc0ffee254729296a45a3885639AC7E10F9d54979", \
          "tag": null \
        }, \
        "userEmail": "joe@example.com", \
        "futureOrderId": "f6491f93dea2bea3db0bc6e76815912a6ace81d9f3a69c7d7d2cdbce28123c09"
      }'

{
  "success": true,
  "code": "ok",
  "data": {
    "orderId": "f6491f93dea2bea3db0bc6e76815912a6ace81d9f3a69c7d7d2cdbce28123c09",
    "exchangeAddress": {
      "address": "DUMMY",
      "tag": null
    },
    "qrCodeUrl": "https://example.com/qrcode.png?x=123",
    "expectedDepositCoinAmount": 0.005,
    "expectedDestinationCoinAmount": 0.1476650575639913,
    "validTill": 1549348022823,
    "frontendTimeout": 1549348015623
  }
}

GET /order/:orderId

Get status for an Order ID.

This endpoint returns the status of the specified orderId.

Response fields:

  • orderId: Order ID
  • exchangeAddress: The wallet the user has to send their funds to - this is an object containing the following properties:
    • address: Wallet address
    • tag: Payment ID or similar secondary identifier (only required for certain currencies)
  • qrCodeUrl: URL to a QR code image which the user can use to initiate the payment from a mobile wallet - will be null after deposit was made
  • destinationAddress: The user's destination wallet which you specified when creating the order - this is an object containing the following properties:
    • address: Wallet address
    • tag: Payment ID or similar secondary identifier (only required for certain currencies)
  • userEmail: The user's email address (if it was specified)
  • userIp: The user's IP address
  • createdAt: Time the order was created (as ms-since-epoch timestamp)
  • status: Current status of the order, can be one of the following:
    • no_deposit: No deposit has yet been made (or an incomplete deposit - in this case, the difference between depositCoinReceived and depositCoinAmount has yet to be sent)
    • confirming: All funds have been deposited, waiting for confirmation on the blockchain
    • exchanging: fox.exchange is currently trading the user's coins
    • sending: The initiation of the transfer of the destination coins to the user's wallet is in progress
    • complete: Order has been completed, coins were sent (this state is entered as soon as the transaction was successfully broadcasted)
    • failed: Some sort of error occured - in this case usually our support team will take care of the problem and the order may later go back into a normal state and complete (if the customer should contact support, a flag customerShouldContactSupport will exist and be set to true)
    • timeout: The order expired
    • unknown: Internal error (this state should normally not be encountered)
  • outputTransactionHash: In the state complete, this contains the transaction ID of the transaction in which the destination coins were transferred to the user,
  • depositCoin: Symbol of the coin the user wanted to exchange from
  • destinationCoin: Symbol of the coin the user wanted to exchange to
  • depositCoinAmount: The amount the user is exchanging
  • destinationCoinAmount: In the state complete, this is the actual amount the user received, otherwise it is the estimated amount the user will receive at the end
  • validTill: The order is valid until this time (given as ms-since-epoch timestamp), any payment submitted afterwards will not be recognized - will be null after deposit was made
  • frontendTimeout: The frontend deposit timer will run out at this time (given as ms-since-epoch timestamp), however payment is still recognized if sent afterwards - will be null after deposit was made
  • depositCoinReceived: Amount of deposit coin already received - this can be relevant when the user sent only part of the funds (in this case the status is still no_deposit but depositCoinReceived is larger than zero, and the application should ask the user to send the remainder)
  • partialAcceptable: In case of incomplete payment (depositCoinReceived is less than depositCoinAmount), this flag may be true. If that's the case, the endpoint /order/:orderId/acceptPartial can be used resize the order to the amount the user sent and proceed with the exchange.

Note: If the status is not complete, the destination amount is approximate and not final. The final amount may slightly differ due to market fluctuations.

Example:

$ curl -XGET 'https://fox.exchange/api/cs/order/f6491f93dea2bea3db0bc6e76815912a6ace81d9f3a69c7d7d2cdbce28123c09' \
  -H 'x-api-key: DEADBEEFDEADBEEF' \
  -H 'x-user-ip: 127.0.0.1'

{
  "success": true,
  "code": "ok",
  "data": {
    "orderId": "f6491f93dea2bea3db0bc6e76815912a6ace81d9f3a69c7d7d2cdbce28123c09",
    "exchangeAddress": {
      "address": "DUMMY",
      "tag": null
    },
    "qrCodeUrl": "https://example.com/qrcode.png?x=123",
    "destinationAddress": {
      "address": "0xc0ffee254729296a45a3885639AC7E10F9d54979",
      "tag": null
    },
    "userEmail": null,
    "userIp": "127.0.0.1",
    "createdAt": 1549333632830,
    "status": "no_deposit",
    "outputTransactionHash": null,
    "depositCoin": "BTC",
    "destinationCoin": "ETH",
    "depositCoinAmount": 0.005,
    "destinationCoinAmount": 0.1476650575639913,
    "validTill": 1549348022823,
    "frontendTimeout": 1549348015623,
    "destinationCoinReceived": 0,
    "partialAcceptable": false
  }
}

POST /order/:orderId/acceptPartial

Accept partial payment for an order.

If the order status has the partialAcceptable flag set to true, you may use this endpoint to proceed with an exchange even though the user has not deposited the full amount. In that case the value of the order will be updated to the amount already sent.

This endpoint returns the status of the specified orderId in the same way as /order/:orderId does.

No body parameters.

GET /orders

Get all orders created with your API Key.

Retrieve all orders created with your API Key in a standard paginated way.

Important: This is a privileged operation. If your API key has a secret token enabled, you need to send the secret token in the x-secret-token header to use this endpoint.

Query parameters:

  • count (optional): Page size (default is 10, maximum is 1000)
  • start (optional): Offset to start at (zero-based)

Response fields:

  • count: Number of results in the current page
  • items: Array of transaction objects (with the schema described above in the response of the /order/:orderId endpoint)
  • totalCount: Total number of results (on all pages)
  • isPrev: Whether a previous page exists
  • isNext: Whether a next page exists

Example:

$ curl -XGET 'https://fox.exchange/api/cs/orders' \
  -H 'x-api-key: DEADBEEFDEADBEEF' \
  -H 'x-user-ip: 127.0.0.1'

{
  "success": true,
  "code": "ok",
  "data": {
    "count": 2,
    "items": [
      {
        "orderId": "f6491f93dea2bea3db0bc6e76815912a6ace81d9f3a69c7d7d2cdbce28123c09",
        "exchangeAddress": {
          "address": "DUMMY",
          "tag": null
        },
        "qrCodeUrl": "https://example.com/qrcode.png?x=123",
        "destinationAddress": {
          "address": "0xc0ffee254729296a45a3885639AC7E10F9d54979",
          "tag": null
        },
        "userEmail": null,
        "userIp": "127.0.0.1",
        "createdAt": 1549333632830,
        "status": "no_deposit",
        "outputTransactionHash": null,
        "depositCoin": "BTC",
        "destinationCoin": "ETH",
        "depositCoinAmount": 0.005,
        "destinationCoinAmount": 0.1476650575639913,
        "validTill": 1549348022823,
        "frontendTimeout": 1549348015623,
        "depositCoinReceived": 0,
        "partialAcceptable": false
      },
      {
        "orderId": "8010d8eed590dc6ae68562e785eda28c9089c36744835a8fc2dc25267c5f40eb",
        "exchangeAddress": {
          "address": "DUMMY",
          "tag": null
        },
        "qrCodeUrl": null,
        "destinationAddress": {
          "address": "0xc0ffee254729296a45a3885639AC7E10F9d54979",
          "tag": null
        },
        "userEmail": null,
        "userIp": "127.0.0.1",
        "createdAt": 1549093439942,
        "status": "confirming",
        "outputTransactionHash": null,
        "depositCoin": "LTC",
        "destinationCoin": "ETH",
        "depositCoinAmount": 0.2,
        "destinationCoinAmount": 0.06474186,
        "validTill": null,
        "frontendTimeout": null,
        "depositCoinReceived": 0.2,
        "partialAcceptable": false
      }
    ],
    "totalCount": 2,
    "isPrev": false,
    "isNext": false
  }
}

Continue reading: PHP Integration Example

Back to documentation overview