TL;DR; -- The documentation is here : https://github.com/Paymium/Paytunia-API-v1-documentationI got a bunch of interesting questions from someone wanting to consume the Bitcoin-Central.net/Paytunia.com API and thought that it might be useful to share it publicly.
If you happen to have questions on the API feel free to ask or comment here.
Paytunia and Bitcoin-Central are basically two different front-ends to the same application, they are served by the same code and they sit on the same database. The main difference is the UI. Also some API calls, and especially these related to trading are only available when using Bitcoin-Central based URIs.
It may seem kind of crazy from an external point of view, but there is a good reason it was set this way. The reason is simply that we tried to get a Paytunia iPhone app approved a while ago, and in order to get it approved we felt that we should not mention any trading at all on the app or on the Paytunia website whatsoever.
That's why Paytunia pretty much only has the wallet functionality of Bitcoin-Central.
In short : use https://bitcoin-central.net as base for *all* your API calls.If you wish to have French localized human strings use
https://fr.bitcoin-central.net, (you could also use
https://en.bitcoin-central.net but English being the default it doesn't really make sense).
I am currently trying to add your platform to my program, but I find it difficult to read you API instructions. It is said that I should use the API of paytunia.com and there are path for the specific requests given. I assume one path could be
https://paytunia.com/order_book. But when I enter that address into my browser, I don't get a JSON object.
What you experience on the order book is perfectly normal, with a RESTful API you request a resource, and if you do not tell the server which format should be used for the response it will default to HTML. If you want the resource returned in JSON you must tell the server. To do so you have two different options : either you add a .json extenstion at the end of the URL (when using a browser for example), or you add a HTTP header "Accept: application/json". That's explained in the "Required HTTP headers" part of the documentation.
I want to add your trading platform to my bot. It is said, that I have to give account id and password as parameters for authentication, but the names of that parameters are not given.
Regarding the authentication of calls there are no specific fields you must pass in the body of your request, in fact the authentication mechanism is standard HTTP Basic authentication (see :
http://en.wikipedia.org/wiki/Basic_access_authentication). The credentials are passed in a header. Any decent HTTP access library will have this functionality already built-in. Check your library if any, otherwise just add the header as described on the wikipedia page. For example if you use cURL just pass a -u 'user:password' option to the command.
When I want to delete an order, I have to put the order ID into the URL. When I want to place an order, I have to send a JSON string. Why, why don't you just use ONE thing: parameters, URLs OR json strings. And if you ask me: sending JSON strings is the worst of the three, I think there is a reason why no other trading platform uses this.
Our API is RESTful, meaning it's based on resource URIs and HTTP verbs. For example with a trade order, if you issue a GET request against the order URI you'll be given the order representation, either in HTML or in JSON, depending on what you request, you may also issue DELETE requests against the same URI to cancel it. If you want to place an order you can just POST to the URI of the order collection (/account/trade_orders IIRC) in order to add an order to the collection. It's just the REST paradigm. Lots of APIs work this way. Regarding the fact that you have to submit a JSON string, you can also pass parameters in the URL in the following way : POST /account/trade_orders?trade_order[amount]=30&trade_order[currency]=EUR&... or as posted form data, it doesn't really matter, it'll get parsed the same way. Have a look here for more information on RESTful web services :
http://en.wikipedia.org/wiki/Representational_state_transfer#RESTful_web_servicesIt is said that a successfull call returns HTTP 200 or 201, but it is not said which is returned when!?
Whenever a resource gets created (you post a trade order, you create a money transfer etc.) you'll get 201. For all other successful responses you'll get a 200.
Yeah, that's a mistake in the documentation you should query /ticker.json (with the optional currency parameter). You're getting an error because you're implictly requesting HTML but there is no specific HTML representation of the ticker. (we'll fix that in the documentation)
Inside the JSON string there is "ppc". Does that mean price per coin? Why don't you define such names?
Yes, we should define them better. But I guess with the example it's pretty transparent, isn't it ?
There is the possibility to give an order type, in the example it is limit order. What other types are there and how do they work?
You can also post market orders. Market orders are like limit orders except they don't have a limit price and will execute at any available market price. Have a look on the trade order creation form, you'll find a link to an in-depth explanation.
Coincidally I saw that there is the possibilty to activate an order, that was placed with unsufficent funds. If there is this feature, why is there no explanation how it works?
That's because I want to remove this feature and simplify the logic around trade order execution. Right now, the way it works is that you can not place an order if you don't have enough funds (BTC or currency) to honor it fully, if you place your order and then withdraw currency or BTC leading to a state where you're unable to honor the order completely it gets inactivated. If you then add funds the order remains inactive, if it wasn't so, users could come to a point where they have old outstanding orders that suddenly execute when they add funds, at prices that aren't in line with the moving price of Bitcoins.
Can I place an order and have it removed instantly when I do not have enough funds?
No, currently if you do not have enough funds, the system will not let you place an order.
This logic should be changed because it is not very intuitive and straightforward.
