Introduction

The KaChing API provides programmatic access to KaChing user accounts, population statistics, and market data.

Core Concepts

Data Types

Every user has exactly one account. Users have one or more portfolios that each represent cash and stock holdings, trade history, and pending trade orders. Currently KaChing limits each user to a single portfolio. This restriction might change in the future.

Users can post messages on walls. In their portfolios, they also maintain watchlists of ticker symbols.

KaChing ranks portfolios on various criteria, such as weekly or quarterly gain. Ranks start with one (highest or best rank) and increase as the ranked criterion worsens.

There is additional site functionality that hasn't yet been made available through the public API. If there is a specific request you need for your application, please ask us.

Requests and Data Formats

Throughout this document we'll use the command-line tool curl to demonstrate certain requests. For example:

curl -X DELETE -H "X-KaChing-RemoteKey: myremotekey" http://www.kaching.com/api/users/123/watchlist/goog

This command would use HTTP method DELETE to remove Google from the user 123's watchlist.

The API adheres to REST principles while recognizing real-world limitations. This means that we use GET, POST, PUT, and DELETE where appropriate, but because some clients allow only the GET/POST HTTP methods, we also provide ways to accomplish PUT/DELETE functionality through POST. Specifically, the named POST argument "X-KaChing-Method" will effectively override the HTTP method:

curl -d "X-KaChing-Method=PUT" -H "X-KaChing-RemoteKey: myremotekey" http://www.kaching.com/api/users/123/watchlist/goog

Currently, all responses are formatted as JSON.

Authentication

Many requests that modify user data require authentication using a KaChing Remote Key. All KaChing users have a Remote Key to provide third party applications access to their KaChing account. A KaChing Remote Key is like a password, except that it is only used for third party applications, so it only provides access to the functionality defined by the API. Users can easily reset it if a third party application abuses the API. Submit a Remote Key using the X-KaChing-RemoteKey HTTP header:

curl -X DELETE -H "X-KaChing-RemoteKey: myremotekey" http://www.kaching.com/api/users/123/watchlist/goog

Errors

KaChing API requests use normal HTTP status code. We summarize a few important error codes:

Resources

In the following section, we use notation explained in the DesignGuidelines.

GET /api/users/:id:

Fetches a specific user. Returns a User.

GET /api/users/:id:/wall

Fetches a specific user's personal wall. Returns a Wall.

GET /api/users/:id:/portfolio

Fetches a specific user's portfolio. Returns a Portfolio.

GET /api/users/:id:/portfolio/trades

Fetches a specific user's portfolio's trades.

Returns {"trades":List[Trade]}.

GET /api/users/:id:/portfolio/trades/:id:

Gets a specific trade for a particular user.

Returns Trade.

Communities

Users belong to communities, or groups. We also have the special everyone community which references all users.

Communities have a dedicated wall and rankings. The everyone community has also an insight which is an aggregate report of portfolio composition.

insight

The insight can be retrieved via GET request

curl http://www.kaching.com/api/communities/everyone/insight

Two optional parameters are supported

• page : int which specifies the page. Pages start at 0. By default, the first page is returned (i.e. page = 0 by default).
• date : date which specifies the date of the insight report. By default, the latest report is returned.

Note: until February 28^th 2008, the two additional parameters can be freely used. Starting in March, they will required an application key with additional credentials.

The top-level object returned is

{"insight":[...]}

where the data in "insight" is a collection of objects. The ordering of the collection is based on the largest differences between the community as a whole and the top managers.

Each object returned resembles

{"everyone":0.00010,"symbol":"EWT","top":0.00851,"trend":"noChange", ...}

which represents one security. Everyone is the percentage ownership by the whole community, top is the percentage ownership by the top 100 people and the trend captures the evolution over the past week of the top ownership.

Data

Trade

deposit

executed order

cash dividend

cash buy-out

stock dividend

stock buy-out

stock buy-out

recapitalization

interest