A little app to track stock portfolios in multiple currencies using REST and JSON.
NOTE: All requests must have ‘key=<your api key>’ in params, as well as any specified params below.
All currencies are ISO 4217 compliant 3-letter codes. As of this writing the only supported currencies are: USD, CAD, EUR, GBP, HKD, AUD, JPY, SGD. This should be enough for most crazy shit.
All responses are one of:
200 (OK) and a json body, as described below 400 (Client Error): the received request was invalid somehow 404 (Not Found): something you're trying to act upon or view doesn't exist 422 (Entity Unprocessable): what you are trying to do can't be done, like executing a cancelled transaction, etc. 5xx (server error): the usual, a problem within the app.
GET /accounts/<account id>
-> JSON object, keys include 'created_at', 'id', 'name', 'updated_at' not very exciting.
GET /accounts/<account id>/portfolios
-> JSON array of portfolio objects. keys include 'name', 'id', 'base_currency' (for reporting purposes and such)
POST /accounts/<account id>/portfolios
params: name, base_currency -> JSON portfolio object (see above) credits the portfolio with USD 5000.00, converted to the given base currency. go hog wild
GET /accounts/<account id>/portfolio/<portfolio id>
-> JSON portfolio object as above PLUS
net_market_value: [currency, amount] - the total value of all of your assets
total_margin: [currency, amount] - the total value you borrowed from your virtual e-broker
currency_assets:
[ {iso: 3-letter code, amount: actual held amount}, ... ]
stock_assets:
[ {symbol: ticker symbol, amount: actual held amount, currency: trading currency of this stock} ]
GET /accounts/<account id>/portfolio/<portfolio id>/forex
-> [ {iso: 3-letter code, amount: actual held amount, market_value: [base_currency, value] }, ... ]
GET /accounts/<account id>/portfolio/<portfolio id>/securities
-> [ {symbol: ticker symbol, amount: actual held amount, market_value: [base_currency, value] }, ... ]
GET /accounts/<account id>/portfolio/<portfolio id>/history
-> [ { transaction }, ... ]
see below for transaction object details
POST /accounts/<account id>/portfolio/<portfolio id>/stocktrade
params: symbol, amount, tradetype ('buy' or 'sell')
-> JSON transaction object, see below. or 422 if this would be impossible, plus a string describing why.
the transaction at this point is OPEN, not actually executed, and is valid for 30 seconds after the quote.
POST /accounts/<account id>/portfolio/<portfolio id>/currencytrade
params: source (currency), target (currency), amount, tradetype ('buy' or 'sell'. source is buying or selling target.)
-> JSON transaction object, see below. or 422 if this would be impossible, plus a string describing why.
the transaction at this point is OPEN, not actually executed, and is valid for 30 seconds after the quote.
{ action_id: #, cost: $ value, count: buy/sell #, currency: currency of transaction, fee: $ value, id: transaction ID, target: thing to be bought or sold (symbol or iso), time_closed: like “2012-04-26T02:13:08Z” (may be null), time_opened: same but never null, transaction_status_id: # } … ]
action IDs: 1 buy stock, 2 sell stock, 3 buy currency, 4 sell currency transaction status IDs: 1 open, 2 closed (fulfilled), 3 cancelled
POST /transactions/<transaction id>/execute
-> the updated transaction object. or 422 if it's expired or you can't afford it or something.
POST /transactions/<transaction id>/cancel
-> the updated transaction object. or 422 if it's expired or it's been already cancelled, or something like that.