[ANN] API for Instawallet

[jav]

I'm happy to announce that there is now an API available for Instawallet. This API can be used to write mobile clients, desktop clients, browser plugins or any other cool stuff you can come up with. There already exists one Android client that uses Instawallet (BitPay), which currently screen-scrapes the Instawallet site, but plans to switch to this API soon.

I will put up the complete documentation on the Instawallet site soon. To see the API in action, I wrote a simple console client for Linux that can be found on GitHub: https://github.com/javgh/iw-console/blob/master/iw-console.py . Screenshot:



Here is a quick overview of the API. All calls return JSON-encoded data:

HTTP POST https://www.instawallet.org/api/v1/new_wallet
    Creates a new Instawallet.
    Example response: {"successful": true, "wallet_id": "1CKAK7zU5NGUlY1n3PK0aw"}
    Note: You can also use HTTP GET, but this is deprecated.

HTTP GET https://www.instawallet.org/api/v1/w/<wallet_id>/address
    Returns the Bitcoin address associated with this Instawallet.
    Example response: {"successful": true, "address": "1PmggT9YKj4HL2iaUs8ukUSvvk3Q1xMv5G"}

HTTP GET https://www.instawallet.org/api/v1/w/<wallet_id>/balance
    Returns the current balance in Bitcoin base units (Satoshis). This means 0.01 BTC will be returned as 1000000.
    Example response: {"successful": true, "balance": 1000000}

HTTP POST https://www.instawallet.org/api/v1/w/<wallet_id>/payment
    Your request needs to include the parameters "address" and "amount". Amount should be in Bitcoin base units (Satoshis). Example response: {"successful": true, "message": "Sent 0.01 BTC to 14Z1mazY4HfysZyMaKudFr63EwHqQT2njz", "message_code": 0}

If an error occurred or the API is not available for some reason, the parameter "succesful" will be false and a "message" as well as a "message_code" will be returned alongside. See the following table for possible messages and codes:
1   The API is currently unavailable.
2   Please provide a Bitcoin address.
3   Please specify the amount you would like to send.
4   Sorry, this does not look like a valid Bitcoin address.
5   Sorry, I was not able to parse the amount field.
6   Sorry, currently only amounts of 0.01 BTC and more are supported.
-4   Sorry, this does not seem to be a valid Bitcoin address
-6   Account has insufficient funds (or not enough confirmations) to complete this action
0   Sent <amount> BTC to <address>

The API also provides a way to get push-notifications on balance change. To use this feature, you first need to get a subscription ID:

HTTP POST https://www.instawallet.org/api/v1/w/<wallet_id>/subscription
    Returns a subscription ID to be used with the push-notification service.
    Example response: {"successful": true, "subscription_id": 1563757213}

The next step is to open a standard socket connection to www.instawallet.org:8202 and to send a JSON object encoding the subscription ID on a single line (terminated by either "\n" or "\r\n") like this: {"subscription_id": 1563757213} . Only the first such object will be accepted, further lines will be ignored. The server should respond with a "ping" (regardless of whether the subscription ID is valid or not). You now simply keep the connection open and the server will send another "ping" each time the balance on the server changes. Note: Because of the subscription mechanism the socket connection can be unencrypted.

Feedback and comments welcome!

[1713935546]

1713935546

[1713935546]

1713935546

[1713935546]

1713935546

[semarjt]

just out of curiosity, why GET /new_wallet, when the other calls all seem more RESTful

GET should be idempotent

[bogeyman]

Hooray for the API! I'll think now I have to code something... 

[jav]

just out of curiosity, why GET /new_wallet, when the other calls all seem more RESTful

GET should be idempotent

Hey! Thx for the feedback. I was indeed a little bit torn between a GET and a POST for this call and this is my first attempt at a RESTful service so I welcome input. I guess my reasoning here is, that this doesn't actually change anything on the server. Since Instawallets are just random links, they are not really "created".

So in that light, if you had a call to /api/random_number would you make it a GET or a POST? (honest question).

And a question about "idempotency": I agree with the general concept, but wonder about situations like this: Let's say you have a /api/current_time call. I would model that as a HTTP GET, even though it doesn't seem idempotent to me - two calls will return different times. Or is it idempotent in the sense, that theoretically the calls could return the same data if you would execute them fast enough?

[dserrano5]

Any chance to have firstbits (currently down due to a bug hunt) integrated? Whenever a given address is shorter than N characters (I think firstbits uses 22 but can't remember right now), a query to the firstbits API is made to discover the full address, and the process continues from that point on.

Thus, we could do: payment 12345 0.01. Sweet, isn't it?

[mndrix]

Thank you.  I hoped you would do this.  I have an interesting project idea that would benefit from this API. Is the API mentioned on your site anywhere?  I didn't see a link.

[bitlotto]

Pretty cool! This will enable a lot of small portable bitcoin related apps! Thank you!

[jav]

Any chance to have firstbits (currently down due to a bug hunt) integrated?

Hey! I think Firstbits is a really cool idea (especially since it only relies on the block chain)  and have been toying with the idea of integrating it into Instawallet. If I do, I will probably implement the algorithm myself, as to not be dependent on external services.

However, there is one thing I find a little worrying: It encourages reuse of Bitcoin addresses, since it can't work otherwise. I don't really want that catching on, especially among merchants, because I think the "proper" way of doing a sale with Bitcoin is to use a fresh address. So for that reason, I have put Firstbit support on the back burner for now. But I'll keep it in mind. Great project nevertheless!

Thank you.  I hoped you would do this.  I have an interesting project idea that would benefit from this API. Is the API mentioned on your site anywhere?  I didn't see a link.

It's not on the site yet, no. This thread is pretty much all the documentation there is. Hopefully I find some time in the next days to move it to the website. PS: I'll be looking forward to your project, I think you did a great job with Coinpal! :-)