Accounts


GET accounts

Description

Get the details for all accounts visible by the requester, sorted ascending by account name.

Resource URL

https://api.optionscity.com/accounts
Authentication Required
HTTP Methods GET
Media Types application/json
Response Object Account
Response Type Standard

Parameters

NameDescriptionRequired?Type
page 1-indexed page to retrieve. Default is 1. No Number
per_page Number of entries returned per page. Default is 20. No Number
query Search for accounts matching the this query by name or account number. No String
trading_enabled If true, returns only accounts enabled for trading. If false, returns only disabled accounts. If left out, returns both types of accounts. No Boolean

Example Request

GET https://api.optionscity.com/accounts

Example Response

[ {
  "name" : "Doug's Account",
  "tag_1" : "12380",
  "clearing_acct_no" : "12380",
  "gmi_office_num" : "123",
  "gmi_acct_num" : "80",
  "org_name" : "Some Organization",
  "clearing_src_id" : 3,
  "clearing_src_name" : "Some Trading Group",
  "id" : 1,
  "trading_enabled" : true,
  "tally_positions" : true,
  "buying_power_margin_percent" : 100,
  "last_sync_date" : "2019-09-23",
  "net_liq" : 12345,
  "net_position_limit" : 100,
  "cti_code" : "4",
  "cash_balance" : 10000,
  "enforce_margin" : false,
  "margin_req" : 2500,
  "margin_status" : "Success",
  "profit_and_loss" : 750,
  "customer_or_firm" : 1,
  "long_us_treasuries" : 25000
} ]

GET accounts/:id

Description

Get the details for the specified account.

Resource URL

https://api.optionscity.com/accounts/:id
Authentication Required
HTTP Methods GET
Media Types application/json
Response Object Account
Response Type Standard

Parameters

NameDescriptionRequired?Type
id The account's City API ID. Yes Number
sync_date Returns account values (balance, net liq. etc.), as of the specified date. The latest available synchronization is used by default. No LocalDate*

Example Request

GET https://api.optionscity.com/accounts/12345

Example Response

{
  "name" : "Doug's Account",
  "tag_1" : "12380",
  "clearing_acct_no" : "12380",
  "gmi_office_num" : "123",
  "gmi_acct_num" : "80",
  "org_name" : "Some Organization",
  "clearing_src_id" : 3,
  "clearing_src_name" : "Some Trading Group",
  "id" : 1,
  "trading_enabled" : true,
  "tally_positions" : true,
  "buying_power_margin_percent" : 100,
  "last_sync_date" : "2019-09-23",
  "net_liq" : 12345,
  "net_position_limit" : 100,
  "cti_code" : "4",
  "cash_balance" : 10000,
  "enforce_margin" : false,
  "margin_req" : 2500,
  "margin_status" : "Success",
  "profit_and_loss" : 750,
  "customer_or_firm" : 1,
  "long_us_treasuries" : 25000
}

POST accounts

Description

Create a new account.

Resource URL

https://api.optionscity.com/accounts
Authentication Required
HTTP Methods POST
Media Types application/json
Response Object Account
Response Type Standard
Request Object Account

Example Request

POST https://api.optionscity.com/accounts
{
  "name" : "Doug's Account",
  "tag_1" : "",
  "clearing_acct_no" : "",
  "gmi_office_num" : "",
  "gmi_acct_num" : "",
  "clearing_src_id" : 3,
  "clearing_src_name" : "",
  "trading_enabled" : true,
  "tally_positions" : true,
  "buying_power_margin_percent" : 100,
  "net_position_limit" : 100,
  "cti_code" : "4",
  "enforce_margin" : false,
  "customer_or_firm" : 1
}

Example Response

{
  "name" : "Doug's Account",
  "tag_1" : "12380",
  "clearing_acct_no" : "12380",
  "gmi_office_num" : "123",
  "gmi_acct_num" : "80",
  "org_name" : "Some Organization",
  "clearing_src_id" : 3,
  "clearing_src_name" : "Some Trading Group",
  "id" : 1,
  "trading_enabled" : true,
  "tally_positions" : true,
  "buying_power_margin_percent" : 100,
  "net_position_limit" : 100,
  "cti_code" : "4",
  "enforce_margin" : false,
  "customer_or_firm" : 1
}

PUT accounts/:id

Description

Modify an existing account.

Resource URL

https://api.optionscity.com/accounts/:id
Authentication Required
HTTP Methods PUT
Media Types application/json
Response Object Account
Response Type Standard
Request Object Account

Parameters

NameDescriptionRequired?Type
id The account ID for the account to modify. Yes Number

Example Request

PUT https://api.optionscity.com/accounts/1
{
  "name" : "Doug's Account",
  "tag_1" : "",
  "clearing_acct_no" : "",
  "gmi_office_num" : "",
  "gmi_acct_num" : "",
  "clearing_src_id" : 3,
  "clearing_src_name" : "",
  "trading_enabled" : true,
  "tally_positions" : true,
  "buying_power_margin_percent" : 100,
  "net_position_limit" : 100,
  "cti_code" : "4",
  "enforce_margin" : false,
  "customer_or_firm" : 1
}

Example Response

{
  "name" : "Doug's Account",
  "tag_1" : "12380",
  "clearing_acct_no" : "12380",
  "gmi_office_num" : "123",
  "gmi_acct_num" : "80",
  "org_name" : "Some Organization",
  "clearing_src_id" : 3,
  "clearing_src_name" : "Some Trading Group",
  "id" : 1,
  "trading_enabled" : true,
  "tally_positions" : true,
  "buying_power_margin_percent" : 100,
  "net_position_limit" : 100,
  "cti_code" : "4",
  "enforce_margin" : false,
  "customer_or_firm" : 1
}

DELETE accounts/:id

Description

Delete an account.

Resource URL

https://api.optionscity.com/accounts/:id
Authentication Required
HTTP Methods DELETE
Media Types --
Response Object None
Response Type Standard

Parameters

NameDescriptionRequired?Type
id The account ID for the account to delete. Yes Number

Example Request

DELETE https://api.optionscity.com/accounts/1

GET accounts/:acct_id/limits

Description

Look up trading limits for all product groups for the specified account.

Resource URL

https://api.optionscity.com/accounts/:acct_id/limits
Authentication Required
HTTP Methods GET
Media Types application/json
Response Object Limits
Response Type Standard

Parameters

NameDescriptionRequired?Type
acct_id The account ID for which to lookup limits. Yes Number

Example Request

GET https://api.optionscity.com/accounts/123/limits

Example Response

[ {
  "prod_group_id" : 34,
  "fut_clip_size" : 10,
  "fut_net_cont_limit" : 10,
  "opt_clip_size" : 20,
  "opt_net_cont_limit" : 20,
  "spr_clip_size" : 40,
  "spr_net_cont_limit" : 40,
  "allow_net_short" : true,
  "daily_cont_limit" : 10
} ]

GET accounts/:acct_id/limits/:prod_grp_id

Description

Look up trading limits for the specified product group and account.

Resource URL

https://api.optionscity.com/accounts/:acct_id/limits/:prod_grp_id
Authentication Required
HTTP Methods GET
Media Types application/json
Response Object Limits
Response Type Standard

Parameters

NameDescriptionRequired?Type
acct_id The account ID for which to lookup limits. Yes Number
prod_grp_id The product group ID for which to lookup limits. Yes Number

Example Request

GET https://api.optionscity.com/accounts/123/limits/456

Example Response

{
  "fut_clip_size" : 10,
  "fut_net_cont_limit" : 10,
  "opt_clip_size" : 20,
  "opt_net_cont_limit" : 20,
  "spr_clip_size" : 40,
  "spr_net_cont_limit" : 40,
  "allow_net_short" : true,
  "daily_cont_limit" : 10
}

POST accounts/:acct_id/limits/:prod_grp_id

Description

Add trading access for the specified product group to the specified account with the given trading limits.

Resource URL

https://api.optionscity.com/accounts/:acct_id/limits/:prod_grp_id
Authentication Required
HTTP Methods POST
Media Types application/json
Response Object Limits
Response Type Standard
Request Object Limits

Parameters

NameDescriptionRequired?Type
acct_id The account ID for which to lookup limits. Yes Number
prod_grp_id The product group ID for which to lookup limits. Yes Number

Example Request

POST https://api.optionscity.com/accounts/123/limits/456
{
  "fut_clip_size" : 10,
  "fut_net_cont_limit" : 10,
  "opt_clip_size" : 20,
  "opt_net_cont_limit" : 20,
  "spr_clip_size" : 40,
  "spr_net_cont_limit" : 40,
  "allow_net_short" : true,
  "daily_cont_limit" : 10
}

Example Response

{
  "fut_clip_size" : 10,
  "fut_net_cont_limit" : 10,
  "opt_clip_size" : 20,
  "opt_net_cont_limit" : 20,
  "spr_clip_size" : 40,
  "spr_net_cont_limit" : 40,
  "allow_net_short" : true,
  "daily_cont_limit" : 10
}

PUT accounts/:acct_id/limits/:prod_grp_id

Description

Update trading limits for the specified product group and account.

Resource URL

https://api.optionscity.com/accounts/:acct_id/limits/:prod_grp_id
Authentication Required
HTTP Methods PUT
Media Types application/json
Response Object Limits
Response Type Standard
Request Object Limits

Parameters

NameDescriptionRequired?Type
acct_id The account ID for which to lookup limits. Yes Number
prod_grp_id The product group ID for which to lookup limits. Yes Number

Example Request

PUT https://api.optionscity.com/accounts/123/limits/456
{
  "fut_clip_size" : 10,
  "fut_net_cont_limit" : 10,
  "opt_clip_size" : 20,
  "opt_net_cont_limit" : 20,
  "spr_clip_size" : 40,
  "spr_net_cont_limit" : 40,
  "allow_net_short" : true,
  "daily_cont_limit" : 10
}

Example Response

{
  "fut_clip_size" : 10,
  "fut_net_cont_limit" : 10,
  "opt_clip_size" : 20,
  "opt_net_cont_limit" : 20,
  "spr_clip_size" : 40,
  "spr_net_cont_limit" : 40,
  "allow_net_short" : true,
  "daily_cont_limit" : 10
}

DELETE accounts/:acct_id/limits/:prod_grp_id

Description

Remove trading access to the specified product group for the specified account.

Resource URL

https://api.optionscity.com/accounts/:acct_id/limits/:prod_grp_id
Authentication Required
HTTP Methods DELETE
Media Types application/json
Response Object None
Response Type Standard

Parameters

NameDescriptionRequired?Type
acct_id The account ID for which to lookup limits. Yes Number
prod_grp_id The product group ID for which to lookup limits. Yes Number

Example Request

DELETE https://api.optionscity.com/accounts/123/limits/456

GET accountuseraccess

Description

Get account-user access records, using optional search parameters to limit the query.

Resource URL

https://api.optionscity.com/accountuseraccess
Authentication Required
HTTP Methods GET
Media Types application/json
Response Object See example
Response Type Standard

Parameters

NameDescriptionRequired?Type
acct_id The account ID for which to look up access rights. No Number
user_id The user ID for which to look up access rights. No Number
page 1-indexed page to retrieve. Default is 1. No Number
per_page Number of entries returned per page. Default is 20. No Number

Example Request

GET https://api.optionscity.com/accountuseraccess?user_id=102

Example Response

[ {
  "id" : 174,
  "acct_id" : 23,
  "user_id" : 102,
  "user" : {
    "email" : "first.last@example.com",
    "first_name" : "Gertrude",
    "last_name" : "Elion",
    "user_type" : "Customer",
    "trading_capacity" : 1,
    "liquidity_provision" : 1,
    "commodity_deriv_indicator" : 0,
    "investment_decision" : 2345,
    "execution_decision" : 6789,
    "trader_id" : "5678",
    "is_professional" : false,
    "id" : 102,
    "is_active" : false
  },
  "tag_50" : "555"
}, {
  "id" : 175,
  "acct_id" : 28,
  "user_id" : 102,
  "user" : {
    "email" : "first.last@example.com",
    "first_name" : "Gertrude",
    "last_name" : "Elion",
    "user_type" : "Customer",
    "trading_capacity" : 1,
    "liquidity_provision" : 1,
    "commodity_deriv_indicator" : 0,
    "investment_decision" : 2345,
    "execution_decision" : 6789,
    "trader_id" : "5678",
    "is_professional" : false,
    "id" : 102,
    "is_active" : false
  },
  "tag_50" : "555"
} ]

GET accountuseraccess/:id

Description

Gets a particular account-user-access record.

Resource URL

https://api.optionscity.com/accountuseraccess/:id
Authentication Required
HTTP Methods GET
Media Types application/json
Response Object See example
Response Type Standard

Example Request

GET https://api.optionscity.com/accountuseraccess/174

Example Response

[ {
  "id" : 174,
  "acct_id" : 23,
  "user_id" : 102,
  "user" : {
    "email" : "first.last@example.com",
    "first_name" : "Gertrude",
    "last_name" : "Elion",
    "user_type" : "Customer",
    "trading_capacity" : 1,
    "liquidity_provision" : 1,
    "commodity_deriv_indicator" : 0,
    "investment_decision" : 2345,
    "execution_decision" : 6789,
    "trader_id" : "5678",
    "is_professional" : false,
    "id" : 102,
    "is_active" : false
  },
  "tag_50" : "555"
} ]

POST accountuseraccess

Description

Adds a new account-user-access record. If you try to POST an acct_id and user_id that already have an existing account-user-access record, an error will be returned. In that case, you should do a PUT to replace the existing record.

Resource URL

https://api.optionscity.com/accountuseraccess
Authentication Required
HTTP Methods POST
Media Types application/json
Response Object See example
Response Type Standard
Request Object See example

Example Request

POST https://api.optionscity.com/usermdaccess
[ {
  "acct_id" : 85,
  "user_id" : 447
} ]

Example Response

[ {
  "id" : 243,
  "acct_id" : 85,
  "user_id" : 447
} ]

PUT accountuseraccess/:id

Description

Replaces a particular account-user-access record.

Resource URL

https://api.optionscity.com/accountuseraccess/:id
Authentication Required
HTTP Methods PUT
Media Types application/json
Response Object See example
Response Type Standard
Request Object See example

Example Request

PUT https://api.optionscity.com/accountuseraccess/243
[ {
  "acct_id" : 85,
  "user_id" : 448
} ]

Example Response

[ {
  "id" : 243,
  "acct_id" : 85,
  "user_id" : 448
} ]

DELETE accountuseraccess/:id

Description

Removes a particular account-user-access record.

Resource URL

https://api.optionscity.com/accountuseraccess/:id
Authentication Required
HTTP Methods DELETE
Media Types --
Response Object None
Response Type Standard

Example Request

DELETE https://api.optionscity.com/accountuseraccess/243

POST accounts/:id/moneyvals

Description

Set money values (net liquidating value, cash balance, U.S. treasuries) on an account, associated with a reference position. Posting these values to the API allows for alternatives to GMI account synchronization.

Resource URL

https://api.optionscity.com/accounts/:id/moneyvals
Authentication Required
HTTP Methods POST
Media Types application/json
Response Object None
Response Type Standard
Request Object AccountMoneyVals

Parameters

NameDescriptionRequired?Type
id The City API ID for the account. Yes Number

Example Request

POST https://api.optionscity.com/accounts/1/moneyvals
{
  "cash_balance" : 50000,
  "net_liq" : 65000,
  "long_us_treasuries" : 20000,
  "as_of" : "2019-09-23"
}

Account Object

Description

A trading account. Every trading transaction must be associated with an account.

Fields

Field Type Optional Description
id Number No The City API ID for the account.
name String No The name given to the account (e.g. Doug's Hedging Account).
clearing_src_id Number No ID for Trading group to which this account belongs (used to be called clearing source).
clearing_src_name String No Name of trading group to which this account belongs (used to be called clearing source).
org_name String Yes Name of the organization that owns the account. Will be returned in queries but is not required/used when creating or updating accounts.
tag_1 String No DEPRECATED: will be removed in a future version. Equal to the new field 'clearing_acct_no'. Tag 1 FIX value used when sending messages to the exchange.
gmi_office_num String No DEPRECATED: will be removed in a future version. Part of the new field 'clearing_acct_no'. The GMI office number identifying this account in GMI files.
gmi_acct_num String No DEPRECATED: will be removed in a future version. Part of the new field 'clearing_acct_no'. The GMI account number identifying this account in GMI files.
clearing_acct_no String No The account identifier used by the clearing firm.
net_position_limit Number Yes The net position limit, if set. Applies globally across all instruments.
buying_power_margin_percent Number No The buying power for the account as a percent of SPAN margin.
trading_enabled Boolean No Whether this account is enabled to submit orders to the exchange.
cti_code String No The CTI code used in FIX messages sent to the exchange.
customer_or_firm Number No The 'customer or firm' code used in FIX messages sent to the exchange.
tally_positions Boolean Yes Whether this account should have positions tallied (setting to false can be usefule for house accounts). Default value is 'true'.
sync_date LocalDate* Yes The trading session date on which all subsequent values were obtained from the clearing firm. Only included if querying for a single account by ID.
net_liq Number Yes An estimation of the live net liquidating value. Calculation is based on the net liquidating value last reported by the clearing firm, adjusted by the profit/loss since the last synchronization (see profit/loss details below). Does not include U.S. Treasuries, and does not account forany deposits or withdrawals that have occurred following the synchronization date. Only included if querying for a single account by ID.
cash_balance Number Yes The cash balance reported by the clearing firm on the synchronization date adjusted by the premium paid/received on any option trades that have occurred since. Does not account for any deposits or withdrawals that have occurred following the synchronization date. Only included if querying for a single account by ID.
enforce_margin Boolean Yes Enables pre-trade margin checks. If this setting is enabled, the system will ensure that submitting a given order won't cause the account's margin to exceed the account's net liquidating value.
margin_req Number Yes The current margin requirement as reported by the exchange. Only included if querying for a single account by ID.
margin_status String Yes If margin is included, the status of the margin value. One of 'Success', 'Processing', or 'Failure'. Only included if querying for a single account by ID.
margin_failure_details String Yes If there was an error calculating the current account margin, the failure details. Only included if querying for a single account by ID.
profit_and_loss Number Yes The estimated profit/loss on the account since the specified clearing firm synchronization date. Last prices are used to determine a market value where required. Only included if querying for a single account by ID.
long_us_treasuries Number Yes The long U.S. Treasury balance reported by the clearing firm on the synchronization date. Does not account for any deposits or withdrawals that have occurred following the synchronization date. Only included if querying for a single account by ID.

JSON Sample

{
  "name" : "Doug's Account",
  "tag_1" : "12380",
  "clearing_acct_no" : "12380",
  "gmi_office_num" : "123",
  "gmi_acct_num" : "80",
  "org_name" : "Some Organization",
  "clearing_src_id" : 3,
  "clearing_src_name" : "Some Trading Group",
  "id" : 1,
  "trading_enabled" : true,
  "tally_positions" : true,
  "buying_power_margin_percent" : 100,
  "last_sync_date" : "2019-09-23",
  "net_liq" : 12345,
  "net_position_limit" : 100,
  "cti_code" : "4",
  "cash_balance" : 10000,
  "enforce_margin" : false,
  "margin_req" : 2500,
  "margin_status" : "Success",
  "profit_and_loss" : 750,
  "customer_or_firm" : 1,
  "long_us_treasuries" : 25000
}

Limits Object

Description

The trading limits enforced for the account-product group pair before an order action is submitted to the exchange.

Fields

Field Type Optional Description
prod_group_id Number Yes The product group ID, provided if not evident from context.
fut_clip_size Number No The maximum acceptable order quantity for all future orders.
fut_net_cont_limit Number No The maximum position that can be held per future contract.
opt_clip_size Number No The maximum acceptable order quantity for all option orders.
opt_net_cont_limit Number No The maximum position that can be held per option contract.
spr_clip_size Number Yes The maximum acceptable order quantity for all spread orders. Optional.
spr_net_cont_limit Number No The maximum position that can be held per spread contract. Optional.
allow_net_short Boolean No Whether orders that could result in short option positions should be permitted.
daily_cont_limit Number Yes The maximum quantity that can be traded per instrument of any type in a given day. Optional.

JSON Sample

{
  "prod_group_id" : 34,
  "fut_clip_size" : 10,
  "fut_net_cont_limit" : 10,
  "opt_clip_size" : 20,
  "opt_net_cont_limit" : 20,
  "spr_clip_size" : 40,
  "spr_net_cont_limit" : 40,
  "allow_net_short" : true,
  "daily_cont_limit" : 10
}

AccountMoneyVals Object

Description

This object is used when posting account money values (net liquidating value, cash balance) associated with a reference position. Posting these values to the API allows for alternatives to GMI account synchronization.

Fields

Field Type Optional Description
as_of LocalDate* No The trading session date following which these values are accurate.
net_liq Number No The net liquidating value for the account following trading on the specified date.
cash_balance Number No The cash balance for the account following trading on the specified date.
long_us_treasuries Number Yes The long U.S. Treasury balance for the account following trading on the specified date.

JSON Sample

{
  "cash_balance" : 50000,
  "net_liq" : 65000,
  "long_us_treasuries" : 20000,
  "as_of" : "2019-09-23"
}

* Date and time elements are ISO-8601 string representations