github.com/bitfinexcom/bitfinex-api-go@v0.0.0-20210608095005-9e0b26f200fb/README.md (about)

     1  # Bitfinex Trading Library for GoLang  - Bitcoin, Ethereum, Ripple and more
     2  
     3  ![https://api.travis-ci.org/bitfinexcom/bitfinex-api-go.svg?branch=master](https://api.travis-ci.org/bitfinexcom/bitfinex-api-go.svg?branch=master)
     4  
     5  A Golang reference implementation of the Bitfinex API for both REST and websocket interaction.
     6  
     7  ### Features
     8  * Official implementation
     9  * REST V1/V2 and Websocket
    10  * Connection multiplexing
    11  * Types for all data schemas
    12  
    13  ## Installation
    14  
    15  ``` bash
    16  go get github.com/bitfinexcom/bitfinex-api-go
    17  ```
    18  
    19  Optional - run the 'trade-feed' example to begin receiving realtime trade updates via the websocket
    20  
    21  ```bash
    22  cd $GOPATH/src/github.com/bitfinexcom/bitfinex-api-go
    23  go run examples/v2/trade-feed/main.go
    24  ```
    25  
    26  ## Quickstart
    27  
    28  ``` go
    29  package main
    30  
    31  import (
    32      "fmt"
    33      "github.com/bitfinexcom/bitfinex-api-go/v2"
    34  )
    35  
    36  func main() {
    37      client := bitfinex.NewClient().Credentials("API_KEY", "API_SEC")
    38  	
    39      // create order
    40      response, err := c.Orders.SubmitOrder(&order.NewRequest{
    41          Symbol: "tBTCUSD",
    42          CID:    time.Now().Unix() / 1000,
    43          Amount: 0.02,
    44          Type: 	"EXCHANGE LIMIT",
    45          Price:  5000,
    46      })
    47      if err != nil {
    48          panic(err)
    49      }
    50  }
    51  ```
    52  
    53  ## Docs
    54  
    55  * <b>[V1](docs/v1.md)</b> - Documentation (depreciated)
    56  * <b>[V2 Rest](docs/rest_v2.md)</b> - Documentation
    57  * <b>[V2 Websocket](docs/ws_v2.md)</b> - Documentation
    58  
    59  ## Examples
    60  
    61  #### Authentication
    62  
    63  ``` go
    64  func main() {
    65      client := bitfinex.NewClient().Credentials("API_KEY", "API_SEC")
    66  }
    67  ```
    68  
    69  #### Subscribe to Trades
    70  
    71  ``` go
    72  // using github.com/bitfinexcom/bitfinex-api-go/v2/websocket as client
    73  _, err := client.SubscribeTrades(context.Background(), "tBTCUSD")
    74  if err != nil {
    75      log.Printf("Could not subscribe to trades: %s", err.Error())
    76  }
    77  ```
    78  
    79  #### Get candles via REST
    80  
    81  ```go
    82  // using github.com/bitfinexcom/bitfinex-api-go/v2/rest as client
    83  os, err := client.Orders.AllHistory()
    84  if err != nil {
    85      log.Fatalf("getting orders: %s", err)
    86  }
    87  ```
    88  
    89  See the <b>[examples](https://github.com/bitfinexcom/bitfinex-api-go/tree/master/examples)</b> directory for more, like:
    90  
    91  - [Creating/updating an order](https://github.com/bitfinexcom/bitfinex-api-go/blob/master/examples/v2/ws-update-order/main.go)
    92  - [Subscribing to orderbook updates](https://github.com/bitfinexcom/bitfinex-api-go/blob/master/examples/v2/book-feed/main.go)
    93  - [Integrating a custom logger](https://github.com/bitfinexcom/bitfinex-api-go/blob/master/examples/v2/ws-custom-logger/main.go)
    94  - [Submitting funding offers](https://github.com/bitfinexcom/bitfinex-api-go/blob/master/examples/v2/rest-funding/main.go)
    95  - [Retrieving active positions](https://github.com/bitfinexcom/bitfinex-api-go/blob/master/examples/v2/rest-positions/main.go)
    96  
    97  ## FAQ
    98  
    99  ### Is there any rate limiting?
   100  
   101  For a Websocket connection there is no limit to the number of requests sent down the connection (unlimited order operations) however an account can only create 15 new connections every 5 mins and each connection is only able to subscribe to 30 inbound data channels. Fortunately this library handles all of the load balancing/multiplexing for channels and will automatically create/destroy new connections when needed, however the user may still encounter the max connections rate limiting error.
   102  
   103  For rest the base limit per-user is 1,000 orders per 5 minute interval, and is shared between all account API connections. It increases proportionally to your trade volume based on the following formula:
   104  
   105  1000 + (TOTAL_PAIRS_PLATFORM * 60 * 5) / (250000000 / USER_VOL_LAST_30d)
   106  
   107  Where TOTAL_PAIRS_PLATFORM is the number of pairs on the Bitfinex platform (currently ~101) and USER_VOL_LAST_30d is in USD.
   108  
   109  ### Will I always receive an `on` packet?
   110  
   111  No; if your order fills immediately, the first packet referencing the order will be an `oc` signaling the order has closed. If the order fills partially immediately after creation, an `on` packet will arrive with a status of `PARTIALLY FILLED...`
   112  
   113  For example, if you submit a `LIMIT` buy for 0.2 BTC and it is added to the order book, an `on` packet will arrive via ws2. After a partial fill of 0.1 BTC, an `ou` packet will arrive, followed by a final `oc` after the remaining 0.1 BTC fills.
   114  
   115  On the other hand, if the order fills immediately for 0.2 BTC, you will only receive an `oc` packet.
   116  
   117  ### My websocket won't connect!
   118  
   119  Did you call `client.Connect()`? :)
   120  
   121  ### nonce too small
   122  
   123  I make multiple parallel request and I receive an error that the nonce is too small. What does it mean?
   124  
   125  Nonces are used to guard against replay attacks. When multiple HTTP requests arrive at the API with the wrong nonce, e.g. because of an async timing issue, the API will reject the request.
   126  
   127  If you need to go parallel, you have to use multiple API keys right now.
   128  
   129  ### How do `te` and `tu` messages differ?
   130  
   131  A `te` packet is sent first to the client immediately after a trade has been matched & executed, followed by a `tu` message once it has completed processing. During times of high load, the `tu` message may be noticably delayed, and as such only the `te` message should be used for a realtime feed.
   132  
   133  ### What are the sequence numbers for?
   134  
   135  If you enable sequencing on v2 of the WS API, each incoming packet will have a public sequence number at the end, along with an auth sequence number in the case of channel `0` packets. The public seq numbers increment on each packet, and the auth seq numbers increment on each authenticated action (new orders, etc). These values allow you to verify that no packets have been missed/dropped, since they always increase monotonically.
   136  
   137  ### What is the difference between R* and P* order books?
   138  
   139  Order books with precision `R0` are considered 'raw' and contain entries for each order submitted to the book, whereas `P*` books contain entries for each price level (which aggregate orders).
   140  
   141  ## Contributing
   142  
   143  1. Fork it (https://github.com/bitfinexcom/bitfinex-api-go/fork)
   144  2. Create your feature branch (`git checkout -b my-new-feature)
   145  3. Commit your changes (`git commit -am 'Add some feature'`)
   146  4. Push to the branch (`git push origin my-new-feature`)
   147  5. Create a new Pull Request