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!