/ 
App-cryp-exchange-0.004
River stage one • 2 direct dependents • 2 total dependents
/ App::cryp::Role::Exchange

NAME

App::cryp::Role::Exchange - Role for interacting with an exchange

VERSION

This document describes version 0.004 of App::cryp::Role::Exchange (from Perl distribution App-cryp-exchange), released on 2018-06-06.

DESCRIPTION

This role describes the common API for interacting with an exchange that all App::cryp::Exchange::* modules follow.

ENVELOPED RESULT

All methods, unless specified otherwise, must return enveloped result:

[$status, $reason, $payload, \%extra]

This result is analogous to an HTTP response; in fact $status mostly uses HTTP response codes. $reason is analogous to HTTP status message. $payload is the actual content (optional if $status is error status). %extra is optional and analogous to HTTP response headers to specify flags or attributes or other metadata.

Some examples of enveloped result:

[200, "OK", ["BTC/USD", "ETH/BTC"]]
[404, "Not found"]

For more details about enveloped result, see Rinci::function.

PROVIDED METHODS

to_canonical_currency

Usage:

$xchg->to_canonical_currency($cur) => str

Convert native currency code to canonical/standardized currency code. Canonical codes are listed in CryptoCurrency::Catalog.

to_native_currency

Usage:

$xchg->to_native_currency($cur) => str

Convert canonical/standardized currency code to exchange-native currency code. Canonical codes are listed in CryptoCurrency::Catalog.

to_canonical_pair

Usage:

$xchg->to_canonical_pair($pair) => str

to_native_pair

Usage:

$xchg->to_native_pair($pair) => str

REQUIRED METHODS

new

Usage:

new(%args) => obj

Constructor. Known arguments:

  • api_key

    String. Required.

  • api_secret

    String. Required.

Some specific exchanges might require more credentials or arguments (e.g. api_passphrase on GDAX); please check with the specific drivers.

Method must return object.

data_native_pair_separator

Should return a single-character string.

data_canonical_currencies

Should return a hashref, a mapping between exchange-native currency codes to canonical/standardized currency codes.

data_reverse_canonical_currencies

Returns hashref, a mapping of canonical/standardized currency codes to exchange native codes. This role already provides an implementation, which calculates the hashref by reversing the hash returned by /"data_canonical_currencies" and caching the result in the instance's _reverse_canonical_currencies key. Driver can provide its own implementation.

list_balances

Usage:

$xchg->list_balances(%args) => [$status, $reason, $payload, \%resmeta]

List account balances.

Method must return enveloped result. Payload must be an array of hashrefs. Each hashref must contain at least these keys:

  • currency

    fiat_or_crpytocurrency.

  • available

    num, balance available for trading i.e. buying.

  • hold

    num, balance that is currently held so not available for trading, e.g. balance currently tied on open buy orders.

  • total

    num, usually available + hold but can also be available + hold + pending_withdraw. Generally not very useful.

Hashref may also contain these keys: pending_withdraw (balance that is in the process of withdrawn to another exchange, etc), unconfirmed (balance that has recently been deposited but unconfirmed e.g. has not reached the minimum number of confirmations).

Hashref may contain additional keys.

list_pairs

Usage:

$xchg->list_pairs(%args) => [$status, $reason, $payload, \%resmeta]

List all pairs available for trading.

Method must return enveloped result. Payload must be an array containing pair names (except when detail argument is set to true, in which case method must return array of records/hashrefs).

Pair names must be in the form of <currency1>/<currency2> where currency1 is cryptocurrency code and <currency2> is the base currency code (fiat or crypto). Some example pair names: BTC/USD, ETH/BTC.

Known arguments:

  • native

    Boolean. Default 0. If set to 1, method must return pair codes in native exchange form instead of canonical/standardized form.

  • detail

    Boolean. Default 0. If set to 1, method must return array of records/hashrefs instead of just array of strings (pair names).

    Record must contain these keys: name (pair name, str). Record can contain additional keys.

get_order_book

Usage:

$xchg->get_order_book(%args) => [$status, $reason, $payload, \%resmeta]

Method should return this payload:

{
    buy => [
        [100, 10 ] , # price, amount
        [ 99,  4.1], # price, amount
        ...
    ],
    sell => [
        [101  , 5.5], # price, amount
        [101.5, 3.1], # price, amount
        ...
    ],
}

Buy (bid, purchase) records must be sorted from highest price to lowest price. Sell (ask, offer) records must be sorted from lowest price to highest.

Known arguments:

  • pair

    String. Pair.

HOMEPAGE

Please visit the project's homepage at https://metacpan.org/release/App-cryp-exchange.

SOURCE

Source repository is at https://github.com/perlancar/perl-App-cryp-exchange.

BUGS

Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=App-cryp-exchange

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

SEE ALSO

AUTHOR

perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2018 by perlancar@cpan.org.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.