API for online information submission | Blog

API for online information submission | Blog

 

If you operate a bitcoin ATM or a teller service listed on our website, you can report online information to be displayed on our website, which currently includes the following (but will be broaden in the future):

  • Online / offline status of your ATM, Teller;
  • Current price and fees at your location for buy and sell transactions;
  • Limits and verifications (can be overwritten in the listing settings directly with a more detailed information, but basic info like limits per transaction / daily limits can be reported and displayed via API as well).

This API is a replacement for an older version, which was described here:
https://coinatmradar.com/blog/recommended-api-for-bitcoin-atm-online-rates/

The information can be reported by a so called ATM manufacturer (for different operators who use their solution), or by a particular operator, if you don’t use any general solution, e.g. you operate your own ATM software, or run own network of teller locations.

In order to submit information you need to have two pieces of information:

  • API provider / operator key
  • End point URL, where you will need to submit information.

To receive them, please contact our support team at [email protected]

API Structure Overview

The API needs to be sent as a JSON POST request with the following data structure:

{
	"providerId": "XXXX",
	"apiTimestamp": "UNIX",
	"locations": [{
		"operatorId": "XXXX",
		"locationId": "unique ID",
		"lastReportedTime": "UNIX",
		"manufacturer": "XXXX",
		"model": "XXXX",
		"address": {
			"street": "XXXX",
			"city": "XXXX",
			"region": "XXXX",
			"postalCode": "XXXX",
			"country": "Alpha-2 code ISO 3166-1",
			"latitude": "123",
			"longitude": "123"
		},
		"business": {
			"name": "XXXX",
			"url": "XXXX",
			"phone": "123",
			"hours": "XXXX"
		},
		"status": {
			"isEnabled": 1/0,
			"cashInEnabled": 1/0,
			"cashOutEnabled": 1/0,
			"lastOnlineTime": "UNIX"
		},
		"mainFiatCurrencyCode": "ISO 4217 3-letter code",
		"mainFiatCurrencySymbol": "X",
		"fiatCurrencies": [{
			"fiatCode": "ISO",
			"cashIn": 1/0,
			"cashOut": 1/0
		},
		...],
		"cryptoCurrencies": [{
			"cryptoCode": "ISO",
			"cashIn": 1/0,
			"cashOut": 1/0,
			"tieredPricing": 1/0,
			"general": {
				"cashInFee": "%",
				"cashOutFee": "%",
				"cashInPirce": "123",
				"cashOutPrice": "123",
				"cashInFixedFee": "123",
				"cashOutFixedFee": "123"
			},
			"tiers": [{
				"amountFrom": "123",
				"amountTo": "123",
				"cashInFee": "%",
				"cashOutFee": "%",
				"cashInPirce": "123",
				"cashOutPrice": "123",
				"cashInFixedFee": "123",
				"cashOutFixedFee": "123"
			},
			...]
		},
		...],
		"cashBoxes": [{
			"boxName": "XXXX",
			"fiatCode": "ISO",
			"type": "In/Out/InOut",
			"amount": "123"
		},
		...],
		"limits": {
			"cashInMinAmt": "123",
			"cashOutMinAmt": "123",
			"cashInTxLimitUnregistered": "123",
			"cashInDailyLimitUnregistered": "123",
			"cashInLifeLimitUnregistered": "123",
			"cashOutTxLimitUnregistered": "123",
			"cashOutdailyLimitUnregistered": "123",
			"cashOutLifeLimitUnregistered": "123",
			"cashInTxLimitRegistered": "123",
			"cashInDailyLimitRegistered": "123",
			"cashInLifeLimitRegistered": "123",
			"cashOutTxLimitRegistered": "123",
			"cashOutdailyLimitRegistered": "123",
			"cashOutLifeLimitRegistered": "123"
		},
		"verifications": [{
			"amountFrom": "123",
			"amountTo": "123",
			"unregistered": 1/0,
			"name": 1/0,
			"dob": 1/0,
			"sms": 1/0,
			"idScan": 1/0,
			"ssn": 1/0,
			"photoId": 1/0,
			"proofOfFunds": 1/0,
			"proofOfResidence": 1/0,
			"enhanced": 1/0
		},
		...]
		
	},
	...]
}

For the purpose of description there are two types of transactions:

  • Buy transaction (means a customer buys cryptocurrency and pays in cash). These transactions are also referred as “Cash IN” in the API;
  • Sell transactions (means a customer sells cryptocurrency and receives cash). These transactions are also referred as “Cash OUT” in the API.

API Fields Description

  • providerId (required, text) – a key, should be requested from our support;
  • apiTimestamp (required, int) – current UNIX formatted time;
  • locations (required, array of objects) – one or more locations data objects;
    • operatorId (required, text) – a key, should be requested from our support;
    • locationId (required, text 50 chars max) – your internal location identifier, should be unique across the same operator locations;
    • lastReportedTime (required, int) – UNIX time of last information state for the location;
    • manufacturer (optional, text 100 chars max) – name of the manufacturer/software provider;
    • model (optional, text 100 chars max) – name of the model of the ATM / Teller;
    • address (optional, object) – object with address details;
      • street (optional, text 250 chars max) – street name and house number;
      • city (optional, text 250 chars max) – name of the city;
      • region (optional, text 250 chars max) – area name, e.g. in the U.S. it is a state name;
      • postalCode (optional, text 250 chars max) – zip code;
      • country (optional, text 2 chars max) – Alpha-2 code ISO 3166-1;
      • latitude (optional, decimal) – latitude of the location;
      • longitude (optional, decimal) – longitude of the location;
    • business (optional, object) – object with business details (a place where the ATM is located, or teller service is provided) for the location;
      • name (optional, text 250 chars max) – the name of place;
      • url (optional, text 250 chars max) – web page of the location (! not the website of your service, can coincide only when you provide the service from your premises, e.g. office);
      • phone (optional, text 20 chars max) – international format phone number;
      • hours (optional, text) – open hours of the business, when the customers can come to make the transaction);
    • status (required, object) – object with current status meta information;
      • isEnabled (required, int 1/0) – whether the location is currently in operation;
      • cashInEnabled (required, int 1/0) – whether the location currently supports buy operations. Important: this information is about the current state, e.g. in general your ATM support buy transaction (you report 1 for this flag in fiat anc crypto blocks below), but currently you don’t have crypto liquidity, hence you report 0 here;
      • cashOutEnabled (required, int 1/0) – similarly this flag indicates whether currently sell transactions are possible at your location. This is not general infromation whether you support sell option, but current status only. E.g. you don’t have cash inside the mahine, hence user cannot withdraw cash currently and finalize sell transaction, in this case 0 should be reported;
      • lastOnlineTime (required, int) – UNIX formatter time, when the ATM was last online. If the ATM is turned off, you need to report, when it was last time operational;
    • mainFiatCurrencyCode (required, text 3 chars) – ISO 4217 3-letter code of the main fiat currency at your location. You can support several fiat currencies, but one should be marked as main, usually it is the main currency of the country, where the location is placed;
    • mainFiatCurrencySymbol (optional, text 3 chars max) – the symbol of the main fiat currency, e.g. $ for USD, € for EUR etc. The symbol is used as a short form of the currency, when displayed in the fees section of the listings;
    • fiatCurrencies (required, array of objects) – details about fiat currencies supported by the locaiton. There should be at least 1 object reported. In case there are several currencies are supported, several objects should be provided;
      • fiatCode (required, text 3 chars) – ISO 4217 3-letter code of the currency;
      • cashIn (required, int 1/0) – whether buy transactions are supported in general at this location for the particular fiat currency;
      • cashOut (required, int 1/0) – whether sell transactions are supported in general at this locations for the particular fiat currency;
    • cryptoCurrencies (required, array of objects) – details about crypto currencies supported at this location. There should be at least 1 object reported. In case there are several currencies are supported, several objects should be provided;
      • cryptoCode (required, text 5 charts max) – a crypto currency code. Currently supported: BTC, BCH, ETH, LTC, DOGE, DASH, ZEC, XMR, LBTC (lightning BTC), XRP, USDT;
      • cashIn (required, int 1/0) – whether buy transactions are supported in general at this location for the particular crypto currency;
      • cashOut (required, int 1/0) – whether sell transactions are supported in general at this location for the particular cryptocurrency;
      • tieredPricing (required, int 1/0) – whether the pricing information is provided as general (the same fees / price for any amount), or prices and fees are set in tiers (for different amount ranges). When the prices / fees are not reported set as 0;
      • general (optional, object) – general pricing details;
        • cashInFee (optional, decimal) – fees set for buy transactions in percentages, e.g. “5.6”;
        • cashOutFee (optional, decimal) – fees set for sell transactions in percentage, e.g. “5.6”;
        • cashInPrice (optional, decimal) – price for buy transactions in mainFiatCurrency units;
        • cashOutPrice (optional, decimal) – price for sell transactions in mainFiatCurrency units;
        • cashInFixedFee (optional, decimal) – fixed fee charged per transaction set in mainFiatCurrency units;
        • cashOutFixedFee (optional, decimal) – fixed fee charged per transaction in mainFiatCurrency units;
      • tiers (required only when tieredPricing = 1, array of objects) – if the prices are provided for tiers, there needs to be at least 2 objects with tiered pricing;
        • amountFrom (required, int) – lower range border for the transaction amounts;
        • amountTo (required, int) – upper range border for the transaction. When there are several tiers provided the amountTo of the previous tier should be 1 unit less than amountFrom of the current tier, e.g. 0-999 and 1000-4999 or 0-1000 and 1001-5000;
        • cashInFee, cashOutFee, cashInPrice, cashOutPrice, cashInFixedFee, cashOutFixedFee – same as for general object (see above), but just for each separate tier;
      • cashBoxes (optional, array of objects) – information about cash balance of the ATM can be provided. Each object needs to contain data about each separate cassette and direction available;
        • boxName (required, text 100 chars max) – unique name/identifier of the cassette;
        • fiatCode (required, text 3 chars) – ISO 4217 3-letter code of the currency;
        • type (required, domain of values) – direction of the operations supported by the cassette. One of the following to be defined: “In” (a cash acceptor for supporting buy transactions), “Out” (a cash dispenser to support sell transactions), “InOut” (recycler that can do both accept and dispense cash banknotes);
        • amount (required, int) – amount of cash in the fiat currency untis;
      • limits (optional, object) – data about limits set at the ATM / Teller. All unregistered limits apply when the customer can do a no-KYC transaction. When at least 1 verification is needed (e.g. SMS) – such limits should be reflected in the registered fields. When there are several tiers of verification, the limits to be provided for the maximum possible amounts. E.g. when the user can do $1000 per transaction with SMS verification, but $5000 per transaction with SMS verification and ID scan verficiation, the $5000 limit to be provided for the registered limit field. All the amounts to be provided in the mainFiatCurrency untis;
        • cashInMinAmt (optional, int) – the minimum possible buy transaction;
        • cashOutMinAmt (optional, imt) – the minimum possible sell transaction;
        • cashInTxLimitUnregistered (optional, int) – maximum possible amount to buy crypto per transaction for unregistered users;
        • cashInDailyLimitUnregistered (optional, int) – maximum possible amount to buy crypto per day for unregistered users;
        • cashInLifeLimitUnregistered (optional, int) – maximum possible amount to buy crypto per user for unregistered users;
        • cashOutTxLimitUnregistered (optional, int) – maximum possible amount to sell crypto per transaction for unregistered users;
        • cashOutDailyLimitUnregistered (optional, int) – maximum possible amount to sell crypto per day for unregistered users;
        • cashOutLifeLimitUnregistered (optional, int) – maximum possible amount to sell crypto per user for unregistered users;
        • cashInTxLimitRegistered (optional, int) – maximum possible amount to buy crypto per transaction for registered users;
        • cashInDailyLimitRegistered (optional, int) – maximum possible amount to buy crypto per day for registered users;
        • cashInLifeLimitRegistered (optional, int) – maximum possible amount to buy crypto per user for registered users;
        • cashOutTxLimitRegistered (optional, int) – maximum possible amount to sell crypto per transaction for registered users;
        • cashOutDailyLimitRegistered (optional, int) – maximum possible amount to sell crypto per day for registered users;
        • cashOutLifeLimitRegistered (optional, int) – maximum possible amount to sell crypto per user for registered users;
      • verifications (optional, array of objects) – data about required verifications for different amounts (in mainFiatCurrency units);
        • amountFrom (required, int) – lower bound of range amount;
        • amountTo (required, int) – upper bound of range amount. When there are several tiers, they should be order sequentially one by one so that current tier amountFrom is 1 unit larger than amountTo in the previous tier;
        • unregistered (optional, int 1/0) – if possible to transact while being unregistered. In case unregistered flag is set as 1, no other verification can be provided as 1 within the same tier;
        • name (optional, int 1/0) – user is required to provide a full name;
        • dob (optional, int 1/0) – user is required to provide a date of birth;
        • sms (optional, int 1/0) – SMS verification required;
        • idScan (optional, int 1/0) – ID scan or ID photo via camera is required;
        • ssn (optional, int 1/0) – Social Security Number is required;
        • photoId (optional, int 1/0) – photo of a person with ID is required. In case of just ID phot required – please use idScan = 1 instead;
        • proofOfFunds (optional, int 1/0) – proof of funds is required;
        • proofOfResidence (optional, int 1/0) – proof of residence / address is required, e.g. eleecitricy bill within last 3 months;
        • enhanced (optional, int 1/0) – any other form of verification required, which is not listed above.

API Responses

As a response you will receive a JSON code with the following strucutre:

  • In case the result is successful and the data is reported properly, you will receive a 200 code response with the following JSON: {“success”: “true”, “error”:””}
  • In case of an error, you will receive a code 400 response with the following JSON: {“success”:”false”, “error”:”XXXX”}, where XXXX will be a description of the error occurred, usually some problem in the data reported that needs to be fixed.

API Usage

Once you implement the submission of the information to the API, you will need to map the listing on our website with information reported for your location.

In order to do this, please set the ID of the location in the settings for external ID of the listing:

The ID should be of the following format: OOOO_LLLL, where OOOO – is the “operatorId” value, LLLL – unique “locationId” value for this ATM/Teller (both are passed in the API above). Operator ID and location ID should be separated with a underscore symbol “_”.



Source link

Leave a Comment

Your email address will not be published. Required fields are marked *