Requirements for Exchange Rate Export File (EREF)¶

This page contains the standards for exchange rate export files (EREF) supported by BestChange. Before an exchanger can get listed on the BestChange directory, it must create an EREF that adheres to the standards listed below, upload the file to its website, and give the BestChange administration a link to the file together with all the other details required for listing. The EREF must be updated non-stop to make sure the exchanger’s rates are correct and up-to-date at all times.

Current version: 1.1

An example of an exchange rate export file.

<?xml version="1.0" encoding="UTF-8"?>
<rates
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="https://docs.bestchange.biz/schema/1.1.xsd"
>
    <item>
        <from>USDT</from>
        <to>CASHUSD</to>
        <in>1</in>
        <out>1.2</out>
        <amount>2000000</amount>
        <frommin>100</frommin>
        <frommax>1000</frommax>
        <tomin>120</tomin>
        <tomax>1200</tomax>
        <fromfee>10</fromfee>
        <tofee>0.01%</tofee>
        <city>FNCH</city>
        <param>manual</param>
    </item>
</rates>

More examples.

The export file must be an XML file.
The decimal separator must be a full stop/period (.).
The root element must be: rates.
Each trading pair must be specified in an item element.

EREF Placement Recommendations¶

The HTTP header of the Content-Type response must be application/xml.
To reduce the load on the exchanger’s server, either of the following HTTP headers are recommended for the response: ETag or Last-Modified.
UTF-8 encoding is required.

item element¶

Required elements¶

from

The code of the source currency, i.e. the currency the exchanger receives from the customer.

to

The code of the target currency, i.e. the currency the exchanger sends to the customer.

in

The amount of the from currency the customer must give.

out

The amount of the to currency the customer will receive.

amount

The exchanger’s reserves of the to currency.

frommin

The minimum amount that the exchanger can accept from a customer within a single order; it is specified in the from currency.

<frommin>4.1</frommin>

Note

In version 1.0, this parameter was specified in the minamount element. As part of backward compatibility, this element will be supported in version 1.1.

Important

In version 1.1, currency code specification has limited functionality. Learn more

frommax

The maximum amount that the exchanger can accept from a customer within a single order; it is specified in the from currency.

<frommax>5000</frommax>

Note

In version 1.0, this parameter was specified in the minamount element. As part of backward compatibility, this element will be supported in version 1.1.

Important

In version 1.1, currency code specification has limited functionality. Learn more

Optional elements¶

tomin

The minimum amount that an exchange office can transfer to a customer in a single exchange order; must be indicated in the to currency.

<tomin>4.1</tomin>

tomax

The maximum amount that an exchange office can transfer to a customer in a single exchange order; must be indicated in the to currency.

<tomax>5000</tomax>

fromfee

An additional fee added to the amount the customer transfers to the exchanger. Must be specified with the national currency code; is not part of the exchange rate.

<fromfee>2.15</fromfee>

Note

You can use the % sign to specify the fee as a percentage (%).

Important

In version 1.1, currency code specification has limited functionality. Learn more

tofee

An additional fee subtracted from the amount the exchanger transfers to the customer. Must be specified with the national currency code; is not part of the exchange rate.

<tofee>30</tofee>

Note

You can use the % sign to specify the fee as a percentage (%).

Important

In version 1.1, currency code specification has limited functionality. Learn more

floating

This indicates a fluctuating exchange rate. Its value must be specified in minutes to show the periods during which the exchange rate will be fixed. If the rate is not fixed for any amount of time, the value must be set as 0.

If the exchanger’s rate is fixed until the actual exchange rate fluctuates by a certain percentage, the value can be specified as a percentage with the help of %.

delay

A param indicating a delayed exchange. The duration of the delay must be specified in minutes.

param

This element allows to specify additional params.

If there are several additional params, they must be comma-separated.

<param>manual,juridical</param>

Spaces between params are allowed.

<param>manual, juridical, verifying</param>

Deprecated since 1.1

Starting from version 1.1, it is recommended to use separate elements for parameters. Learn more

city

This element is used to specify the physical location of the exchange. This element must only be specified for exchanges involving cash. The export file can contain trading pairs with different locations specified.

<city>MSK</city>

If the same exchange conditions are valid for several locations, the locations can be specified inside a single item element: one city element can contain the codes for several locations separated with a comma.

<city>MSK,DUBAI,KIEV</city>

Params¶

atm: An exchange within the chosen trading pair can only be performed via a Bitcoin ATM in the chosen city. This element can be used for exchanges involving cash.
card2card: The exchanger accepts customers’ funds via Card2Card transfers (without a merchant account). This element must only be used for Visa/MasterCard —› * exchanges.
cardverify: While processing an exchange order, the exchanger can request bank card verification.
delivery: The exchanger does not have a brick-and-mortar office in the chosen city. The delivery cost must be included in the exchange rate or indicated with an “Additional Fee” sign.
manual: This is a required param for trading pairs that are processed manually or in a semi-automatic mode, which can cause delays.
juridical: The exchanger transfers funds using the payment details of a legal entity or an individual entrepreneur. This param must only be present for exchanges that involve bank transfers (* —› Any Bank).
otherin: The receipt of the customer’s funds is realized via a third-party payment system that is different from the one specified in the from element.
otherout: The exchanged funds are paid out via a third-party payment system that is different from the one specified in the to element.
reg: Customers are required to register on the exchanger’s website to be able to order an exchange.
verifying: While processing an exchange order, the exchanger can request the customer’s ID.

Codes for cities and currencies¶

A complete and updated list of currencies

A complete and updated list of cities

Example¶

<?xml version="1.0" encoding="UTF-8"?>
<rates xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:noNamespaceSchemaLocation="https://docs.bestchange.biz/schema/1.1.xsd"
>
    <!-- General example -->
    <item>
        <!-- 1 WMZ to 30.593562 WMX -->
        <from>WMZ</from>
        <to>WMX</to>
        <in>1</in>
        <out>30.593562</out>
        <!-- The exchanger’s reserve of WMX -->
        <amount>572962.42</amount>

        <!-- The customer can exchange 3 to 1,000 WMZ in a single order -->
        <frommin>3</frommin>
        <frommax>1000</frommax>
    </item>

    <!-- If the customer wants to receive cash (CASH), then the city element must be specified -->
    <item>
        <!-- 1 XRP for 26.745435 RUB in cash in Rostov-on-Don (RSND) -->
        <from>XRP</from>
        <to>CASHRUB</to>
        <in>1</in>
        <out>26.745435</out>
        <!-- RUB cash reserve at the exchanger in this city -->
        <amount>26743394.68515</amount>

        <city>RSND</city>

        <!-- The customer can exchange 5,000 to 700,000 XRP in a single order. -->
        <frommin>5000</frommin>
        <frommax>700000</frommax>
        <param>manual</param>

        <tofee>1%</tofee>
        <fromfee>1%</fromfee>
    </item>

    <!-- The example contains all possible elements -->
    <item>
        <from>ADVCUSD</from>
        <to>PMUSD</to>
        <in>1</in>
        <out>0.978</out>
        <amount>2921.42</amount>

        <frommin>2</frommin>
        <frommax>2000</frommax>
        <!-- Several params in one element -->
        <param>manual,juridical,verifying,reg,cardverify,card2card,otherin,otherout</param>

        <fromfee>1%</fromfee>
        <tofee>1%</tofee>

        <delay>10</delay>
        <floating>10%</floating>
    </item>

</rates>