lightwire

A little app to track stock portfolios in multiple currencies using REST and JSON.

API

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.

accounts

GET /accounts/<account id>

-> JSON object, keys include 'created_at', 'id', 'name', 'updated_at'
not very exciting.

portfolios

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.

transactions

the transaction object

{ 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

actions

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.