Cryptocurrency Exchange. OWNR Wallet Partner Integration Documentation - OWNR Support
bitcoin background
language
How can we help you today?

Cryptocurrency Exchange. OWNR Wallet Partner Integration Documentation

Contents

A. Description and security
B. Basic use case
C. API documentation

A. Description and security

Primary URL for API: https://pxapi.ownrdata.com/v1
Swagger API documentation: https://pxapi.ownrdata.com
For you to be able to use API or review specifications, the manager of your partner account needs to provide a partner unique individual SSL certificate issued by OWNR. The certificate may be delivered as a PKCS12 container and a password. Use your OS tools and/or web browser for installing the certificate into your own system and/or your server.
To use the CURL command for testing, you may unzip the certificate, for example:

openssl pkcs12 -in cert.p12 -out cert.crt -clcerts -nokeys
openssl pkcs12 -in cert.p12 -out cert.key -nocerts -nodes

curl \
  -s \
  --key cert.key \
  --cert cert.crt \
  -H "X-OWNR-API-KEY: pak_ioywrb7how7mz4cvwtcn9jvuefz9h4" \
  https://pxapi.ownrdata.com/v1/ping

Each request must include the “X-OWNR-API-KEY” header, which needs to contain a valid API key provided by OWNR.

B. Basic use case

  1. Use GET /order_params for obtaining an initial order amount at current rates.
  2. Use POST /order for creating a new order. The request body must include refund_address, in case of an error the funds refunds at the indicated address. Save order_id from body of response. Next, the response must contain field pay_in_address. This is the address where the amount of the created order shall be transferred.
  3. Use GET /order for receiving order status in the course of its life cycle.
  4. Use GET /metadata for receiving funds available for payout.

C. API documenentaion

Specifications of all routes, parameters, and responses are available at Swagger (OpenAPI): https://pxapi.ownrdata.com

C.1. Authentication

All requests must be authenticated. The two-factor authentication is used.
Factor 1: User SSL certificate provided by OWNR. Must be used in all requests including API documentation page.
Factor 2: API key provided by OWNR. Must be included in HTTP header X-OWNR-API-KEY in all requests.
To check the connection of the certificate and API key, the request for routing GET /ping must be executed.

C.2. Orders

POST /order

Creating a new order.
Below is an example of parameters which shall be passed as a JSON object:

{
  "partner_order_id": "123123",
  "from_cryptocurrency": "LTC",
  "to_cryptocurrency": "BTC",
  "amount": "1.00",
  "partner_comission_percent": "1.5",
  "pay_out_address": "1QB59uYoC4XML7qXDsEoCXMJKaamYgZ7yJ",
  "refund_address": "Lc7QzUoWD3YwoMqaaXrredRUW2aQKypcSr"
}
  • Required parameters:

from_cryptocurrency base cryptocurrency: if you are converting BTC to LTC, BTC is the from_cryptocurrency
to_cryptocurrency quote (counter) cryptocurrency, i.e. the one you are converting the base cryptocurrency to; in the example above, it is LTC
amount the amount to be converted
pay_out_address the address for cryptocurrency payout
refund_address the refund address in case of an erroneous transaction

  • Optional parameters:

partner_order_id order ID provided by partner; it may be any line containing up to 256 symbols safe for URL addresses
partner_comission_percent partner’s fee in percent

  • In case of a successful request, the response will have status code HTTP 200 and contain a JSON object. For example:
{
  "order_id": "cxpo_zwzybc7w5a9ctdh9cqndn2qjntxh6d",
  "partner_order_id": "123123",
  "from_cryptocurrency": "LTC",
  "to_cryptocurrency": "BTC",
  "pay_out_amount": "0.003989120000000000000000",
  "pay_in_amount": "1.000000000000000000000000",
  "refund_amount": null,
  "pay_out_address": "1QB59uYoC4XML7qXDsEoCXMJKaamYgZ7yJ",
  "pay_in_address": "LMbvecF6BRXYp8asTw2REFTAddB7teZgqU",
  "pay_out_tx_id": null,
  "pay_in_tx_id": null,
  "refund_address": "Lc7QzUoWD3YwoMqaaXrredRUW2aQKypcSr",
  "refund_tx_id": null,
  "partner_comission_percent": "1.500000000000000000000000",
  "estimated_reward": "2.3571",
  "rate": "0.00398912",
  "created_at": "2020-11-29T18:56:25.328Z",
  "updated_at": "2020-11-29T18:56:25.328Z",
  "expires_at": "2020-11-29T19:56:24.440Z",
  "status": "waiting_for_receive",
  "refund_status": null,
  "error_details": null,
  "refund_error_details": null
}

order_id unique order ID generated by OWNR. It will be required for further requests related to the order.
partner_order_id order ID provided by partner; it may be any line containing up to 256 symbols safe for URL addresses
from_cryptocurrency base cryptocurrency (the one from which the conversion is made)
to_cryptocurrency quote (counter) cryptocurrency (the one you are converting the base cryptocurrency to)
pay_out_amount the amount to be received upon exchange
pay_in_amount the amount to be transferred
refund_amount the amount to be refunded in case of an erroneous transaction
pay_out_address the address for cryptocurrency payout
pay_in_address the recipient address for the amount shown in the field pay_in_amount
pay_out_tx_id outgoing transaction ID (hash)
pay_in_tx_id incoming transaction ID (hash)
refund_address the refund address in case of an erroneous transaction
refund_tx_id transaction ID (hash) for the amount refunded in case of an error
partner_comission_percent partner’s fee in percent
estimated_reward the estimated amount to be sent to the partner upon order completion
rate rate calculated as a ratio of from_cryptocurrency/to_cryptocurrency. This rate is used to calculate pay_in_amount
created_at date and time of the order creation
updated_at date and time of the order renewal
expires_at date and time of the order expiration
status order status. Order statuses are listed below:

  1. ‘waiting_for_receive’ – waiting for the from_cryptocurrency to be received
  2. ‘mempool_detected’ – outgoing transaction detected in mempool
  3. ‘receiving’ – receiving the from_cryptocurrency
  4. ‘exchange_pending’ – sending of the to_cryptocurrency is pending
  5. ‘sending’ – sending the to_cryptocurrency is in progress
  6. ‘completed’ – sending the to_cryptocurrency is completed
  7. ‘expired’ – the order is expired
  8. ‘refunded’ – order was refunded
  9. ‘error’ – error occurred

refund_status refund status
error_details error details
refund_error_details refund error details

  • In case of erroneous request execution, please see section “C.4.”

Possible error codes:

PAY_IN_ADDRESS_NOT_VALID invalid recipient address
REFUND_ADDRESS_NOT_VALID invalid refund address
FROM_CRYPTOCURRENCY_NOT_SUPPORTED base cryptocurrency is not supported
TO_CRYPTOCURRENCY_NOT_SUPPORTED counter cryptocurrency is not supported
PAY_IN_AMOUNT_LESSER_THAN_MIN_LIMIT the amount is less than the allowed limit
PAY_IN_AMOUNT_EXCEEDS_MAX_LIMIT the amount exceeds the allowed limit
PAY_IN_AMOUNT_NEGATIVE the amount cannot be negative
PAY_IN_AMOUNT_NOT_VALID invalid amount
PARTNER_COMMISSION_PERCENT_NEGATIVE partner’s fee cannot be negative
PARTNER_COMMISSION_PERCENT_EXCEEDS_MAX_LIMIT partner’s fee exceeds the allowed limit

POST /order_by_pay_out_amount

Creation of the new order calculated in accordance with the payout amount.
The description of the parameters is the same as in the POST /order command but for the ‘amount’ field which is called pay_out_amount.

GET /order_params

To get the amount that shall be received upon exchange. The amount is calculated at current rates
Parameters to be used inside request parameters are:

  • Required parameters:

from_cryptocurrency from which cryptocurrency
to_cryptocurrency to which cryptocurrency
amount the amount to be transferred

  • Optional parameters:

partner_comission_percent partner’s fee in percent

URL example:

https://pxapi.ownrdata.com/v1/order_params?from_cryptocurrency=LTC&to_cryptocurrency=BTC&amount=1&partner_comission_percent=1.5

In case of a successful request, the response will have status code HTTP 200 and a JSON object. For example:

{
  "from_cryptocurrency": "LTC",
  "to_cryptocurrency": "BTC",
  "pay_out_amount": "0.003859",
  "pay_in_amount": "1",
  "rate": "0.0038594"
}

from_cryptocurrency base cryptocurrency (the one from which the conversion is made)
to_cryptocurrency quote (counter) cryptocurrency (the one you are converting the base cryptocurrency to)
pay_out_amount the amount to be received upon exchange
pay_in_amount the amount to be sent
rate rate to be applied

  • In case of erroneous request execution, please see section “C.4.”

Possible error codes:

AMOUNT_NEGATIVE the amount cannot be negative
AMOUNT_NOT_VALID invalid amount
PARTNER_COMMISSION_PERCENT_NEGATIVE partner’s fee cannot be negative
PARTNER_COMMISSION_PERCENT_NOT_VALID invalid partner’s fee
PARTNER_COMMISSION_PERCENT_MAX_LIMIT partner’s fee exceeds the allowed limit`

GET /order_params_by_pay_out_amount

To receive the amount to be transferred. The amount is calculated at current rates.
Parameters to be transferred inside request parameters:

  • Required parameters:

from_cryptocurrency base cryptocurrency (the one from which the conversion is made)
to_cryptocurrency quote (counter) cryptocurrency (the one you are converting the base cryptocurrency to)
pay_out_amount the amount to be received upon exchange

  • Optional parameters:

partner_comission_percent partner’s fee in percent

URL example:

https://pxapi.ownrdata.com/v1/order_params_by_pay_out_amount?from_cryptocurrency=LTC&to_cryptocurrency=BTC&pay_out_amount=0.003879&partner_comission_percent=1.5

In case of a successful request, the response shall have status code HTTP 200 and a JSON object. For example:

{
  "from_cryptocurrency": "LTC",
  "to_cryptocurrency": "BTC",
  "pay_out_amount": "0.003879",
  "pay_in_amount": "1.005078",
  "rate": "0.0038594"
}

from_cryptocurrency base cryptocurrency
to_cryptocurrency quote (counter) cryptocurrency
pay_out_amount the amount to be received upon exchange
pay_in_amount the amount to be transferred
rate the rate at which the amount is calculated

  • In case of erroneous request execution, please see section “C.4.”

Possible error codes:

PAY_OUT_AMOUNT_NEGATIVE the amount cannot be negative
PAY_OUT_AMOUNT_NOT_VALID invalid amount
PARTNER_COMMISSION_PERCENT_NEGATIVE partner’s fee cannot be negative
PARTNER_COMMISSION_PERCENT_NOT_VALID invalid partner’s fee
PARTNER_COMMISSION_PERCENT_MAX_LIMIT partner’s fee exceeds the allowed limit

GET /orders

Obtaining order list.

Request parameter skip is the number of all entries skipped
Request parameter limit is used to limit the number of entries for obtaining in a response
In case of success, the response status should change to HTTP 200 and have a JSON object, containing the list of orders. The list of order fields may be found in the response POST /order.

  • In case of erroneous request execution, please see section “C.4.”

Possible error codes:

QUERY_FROM_DATE_NOT_VALID invalid date
QUERY_TO_DATE_NOT_VALID invalid date

GET /order/{order_id}

Obtaining current order status.
Parameter order_id should be passed as part of the URL address. It’s a unique order identifier issued by OWNR upon creation of the order.
In case of success, the response status will change to HTTP 200 and have a JSON object, containing order information. The list of order fields may be found in response POST /order.

GET /cryptocurrencies

Obtaining the list of supported cryptocurrencies.
This method does not have any parameters.
In case of success, the response should have status HTTP 200 and a JSON object, containing the list of supported cryptocurrencies.

[
  "USDT",
  "BTC",
  "ETH",
  "LTC",
  "ZEC",
  "DASH"
]

GET /cryptocurrency/{cryptocurrency}/metadata

Obtaining information about the minimum and maximum exchange amounts available for the cryptocurrency in question.
In case of success, the response will have status code HTTP 200 and a JSON object, containing information about minimum and maximum amounts.

{
  "amount_min": "0.003735",
  "amount_max": "9.173548",
  "cryptocurrency": "ETH"
}

amount_min Minimum exchange amount
amount_max Maximum exchange amount
cryptocurrency cryptocurrency to be exchanged

C.3. Finances

GET /ledger

Obtaining the list of the incoming transactions to partner’s account and payouts.
Request parameter skip is the number of the entries skipped.
Request parameter limit is used to limit the number of entries for obtaining in a response.
Request parameter from_date is used to filter entries by time period.
Request parameter to_date is used to filter entries by time period.
In case of success, the response should have status HTTP 200 and a JSON object, containing the list of incoming and outgoing transactions.

For example:

[
  {
    "record_id": "cxpl_4wue3zg3ynksy7as83t6b8pspb5295",
    "record_type": "credit",
    "amount": "500.00",
    "created_at": "2020-11-26T09:45:46.744Z",
    "order_id": null,
    "withdrawal_id": "cxpw_ejr5hok24ei5c9ajn42mzr37j633kb"
  },
  {
    "record_id": "cxpl_f5d2uu4q6fir7b25ywmfbhivf6erww",
    "record_type": "debit",
    "amount": "1.10",
    "created_at": "2020-11-30T09:44:21.242Z",
    "order_id": "cxpo_i89rk6gr8yqf6vut04h5xo5yn45p6d",
    "withdrawal_id": null
  }
]

record_id unique entry ID generated by OWNR
record_type record type which can be credit/debit. The record like credit is created upon successful exchange order. The record like debit is created upon payout execution.
amount amount in USD
created_at date and time of record creation
order_id unique order ID, generated by OWNR upon order creation. Such order ID is only used with record type credit
withdrawal_id unique order ID, generated by OWNR upon order creation. Such order ID is only used with record type debit

  • In case of erroneous request execution, please see section “C.4.”

Possible error codes:

QUERY_FROM_DATE_NOT_VALID invalid date
QUERY_TO_DATE_NOT_VALID invalid date

POST /withdrawal

Payout creation.
Parameters to be passed as a JSON object, for example:

{
  "amount": "2500.00"
}

Required parameters:
amount payout amount.
In case of success, the response will have status HTTP 200 and a JSON object.

For example:

{
  "withdrawal_id": "string",
  "amount": "2500.00",
  "status": "new",
  "created_at": "2020-01-01T01:00:30Z",
  "completed_at": "2020-01-01T01:10:30Z"
}

withdrawal_id unique payout ID generated by OWNR. It should be used for further requests related to the payout
amount payout amount
status payout status. It may be the following:

  1. ‘new’ – new payout awaiting confirmation and completion of the payout
  2. ‘completed’ – payout completed

created_at date and time of the payout creation.
completed_at date and time of the payout completion.

  • In case of erroneous request execution, please see section “C.4.”

Possible error codes:

INSUFFICIENT_FUNDS there are not enough funds for creating a payout

GET /withdrawals

Obtaining the list of payouts.

Request parameter skip is a number of entries skipped.
Request parameter limit is used to limit the number of entries for obtaining in a response.

In case of success, the response will have status HTTP 200 and a JSON object with an array of payouts. The list of payout object fields may be found in response POST /withdrawal.

For example:

[
  {
    "withdrawal_id": "cxpw_ejr5hok24ei5c9ajn42mzr37j633kb",
    "amount": "0.20",
    "status": "completed",
    "created_at": "2020-11-26T09:43:58.890Z",
    "completed_at": "2020-11-26T09:45:46.744Z"
  }
]

GET /withdrawal/{withdrawal_id}

Obtaining the current payout status.
Parameter withdrawal_id should be passed as part of the URL address. It’s a unique payout identifier issued by OWNR upon order creation.
In case of success, the response should have status HTTP 200 and a JSON object containing payout information. The list of payout object fields may be found in response POST /withdrawal.

C.4. Utilities

GET /metadata

Obtaining information about the amount available for a payout.
This method does not have any parameters.
In case of success, the response will have status HTTP 200 and a JSON object with the information about the amount available for a payout.

For example:

{
  "partner_name": "ownr-exchange-partner",
  "total_withdrawable_usd_amount": "5500.97"
}

partner_name partner name
total_withdrawable_usd_amount amount available for a payout

GET /ping

Use this method for troubleshooting connection errors including certificate and API key.
This method does not have any parameters.
In case of success, the response will have status HTTP 200 and a JSON object. For example:

{
  "message": "pong"
}

C.4. Error processing

All errors return as a standard erroneous response, the error code may be found in response body, for example:

{
  "error_code": "INSUFFCIENT_FUNDS"
}

Code statuses

400 – Bad request, response body shall have detailed information about such an error, for example:

{
  "error_details": "The \"body\" parameter is invalid ..."
}

401 – Unauthorized request
403 – Access denied
404 – Requested object not found
405 – Invalid parameters
500 – Server error, response body shall contain error code, for example:

{
  "error_code": "PAY_IN_AMOUNT_LESSER_THAN_MIN_LIMIT"
}

Error codes

Depending on the method, various error codes may occur, specific codes are described inside each method.
General error codes:

MISSING_PARAMETERS not all required parameters were provided
NOT_FOUND object not found
API_KEY_REQUIRED API key is not specified
BAD_CERTIFICATE invalid certificate
FORBIDDEN access forbidden
INTERNAL_SERVER_ERROR unknown internal server error