It's a daunting task, a test of valor. Little documentation had we, and BTC-E left us meditating for hours of their internal working mechanism. The most confusing question is the difference of TransHistory and TradesHistory API calls. I perhaps should document it elsewhere, in a wiki maybe, kindly reply to let me know where do I keep the following documents for easier access for others.
I spend real money to execute real orders which I counter with opposite orders of same value (meaning I didn't speculate) and I used my time. Consider tipping me for sharing this info, address at the signature.
Experiment One:
I issued an order to sell 5BTC.
Result:
------------------------------- TradeHistory: ---------------------------------
'18330625': {'amount': 5,
'is_your_order': 1,
'order_id': 77935084,
'pair': 'btc_usd',
'rate': 969,
'timestamp': 1386258897,
'type': 'sell'},
------------------------------- TransHistory: ---------------------------------
'185562562': {'amount': 5.0,
'currency': 'BTC',
'desc': 'In payment for a warrant :order:77935084:',
'status': 2,
'timestamp': 1386258893,
'type': 5},
'185562750': {'amount': 4835.31,
'currency': 'USD',
'desc': 'Bought 5 BTC from your order :order:77935084: by price 969 USD total 4845 USD (-0.2%)',
'status': 2,
'timestamp': 1386258897,
'type': 4},
The 'desc' field in TransHistory is mind boggin. I sold 5BTC, and the log reads 'Bought 5BTC', from the aspect of the other party I am trading with. BTC-E seems to be turning things up side down. In the API history, it assume the position of the market, when it should assume the position of the user; while in its price ticker, it quotes 'buy' and 'sell' price, from the aspect of you, the user, contrary to finanical professional term 'ask' and 'bid' from the aspect of the market.
We also notice that TradeHistory have only one record for this order, while TransHistory have 2 records. TradeHistory records amount and rate, but not how you split revenue with BTC-E. TransHistory seems to detail that split.
BTC-E charges 0.2% transaction fee. For a revenue of 4845USD, that means 9.690USD fee, and you get 4035.31USD to your own. This is exactly what is shown in the last record of TransHistory.
TransHistory shows your account has 5USD removed for warrant before the trade happens. That is about half of the fee. But, there is no record showing the rest of the fee removed, and it just magically removed. Let's not worry about it as long as they don't over charge us.
About the IDs: TradeHistory's ID '18330625' is 10 times apart from TradeHistory's IDs. We can guess that each TradeHistory maps to a lot TransHistories. But TradeHistory's ID is not referred in TransHistory records. The only way to link these records is the Order ID, given in TradeHistory and quoted in TransHistory.
From timestamp you may notice transaction fee was taken a while before trade occures.
Experiment Two:
This time I sell at a price higher than current, and let the order gradually fill. I also made the amount bigger, 10BTC, twice the previous one, to make sure it filles gradually.
It created 41 entries in the TradeHistory:
'18333675': {'amount': 4.06175,
'is_your_order': 1,
'order_id': 77936808,
'pair': 'btc_usd',
'rate': 965.5,
'timestamp': 1386259479,
'type': 'sell'},
'18333680': {'amount': 0.0225107,
'is_your_order': 1,
'order_id': 77936808,
'pair': 'btc_usd',
'rate': 965.5,
'timestamp': 1386259483,
'type': 'sell'},
... (other 39 records omitted)
The sum of the volume, however, is 10.0000085. I'll forgive the float point inprecision. The TransHistory has 42 records, one more than the TradeHistory. As usuall, a warrant is charged before every other transaction, BTC-E really knows how to put customer interest before theirs:)
'185566733': {'amount': 10.0,
'currency': 'BTC',
'desc': 'In payment for a warrant :order:77936808:',
'status': 2,
'timestamp': 1386259063,
'type': 5},
'185600769': {'amount': 3913.77176062,
'currency': 'USD',
'desc': 'Bought 4.0617452 BTC from your order :order:77936808: by price 965.5 USD total 3921.6149906 USD (-0.2%)',
'status': 2,
'timestamp': 1386259479,
'type': 4},
'185601221': {'amount': 21.69061269,
'currency': 'USD',
'desc': 'Bought 0.0225107 BTC from your order :order:77936808: by price 965.5 USD total 21.73408085 USD (-0.2%)',
'status': 2,
'timestamp': 1386259483,
'type': 4},
... (other 39 records omitted)
So our brief conclusion is:
1. TransHistory is really of no interest unless we are specifically looking for how it internally works. It didn't cover all fees, and it doesn't have a order_id field where we can map our order with.
2. TradeHistory is the only API interesting. However it doesn't support looking up with order_id. If you wish to find out how much of your order is executed, you have to fetch a hundred or more records - as it is shown a 10BTC deal can be easily split to 41 records - and filter out unwanted records in your own code. Let's say their server is too burdened to index for order_id, and we just forgive them.
3. There will be unwanted items in TradeHistory! I have a record like this:
'18335903': {'amount': 7.08416,
'is_your_order': 0,
'order_id': 77967359,
'pair': 'btc_usd',
'rate': 973,
'timestamp': 1386260055,
'type': 'sell'},
Whose record is this? I don't know. It somehow gets mixed into my TradeHistory. I feel sorry BTC-E couldn't make it more elegant.
