cURL Examples

Background

cURL is a command line tool for getting or sending files using URL syntax.

For detailed background info, see here: https://curl.haxx.se/

For a complete list of the command options, see here: https://curl.haxx.se/docs/manpage.html

Getting an Auth Token

Most cURL commands against City API require an Authorization Token.

We have an internal script you can run to get such a token. See here: https://github.com/optionscity/city-api/wiki/Getting-an-Auth-Token

Alternatively, you can cURL for an Auth Token, but you will need the following information:

  • The Client ID from your City API User Profile
  • The Secret from your City API User Profile
  • The login/username of your City API User account (i.e., the email address you use when logging into City API)
  • The password of your City API User account (i.e., the password you use when logging into City API)
  • The customer ID (aka user ID) of your City API User account

The above information, except for your password, is all available from the Profile page, which can be accessed in the upper-righthand corner after logging into City API.

Using the above information, make a cURL command modeled after this one:

curl -v -u "yourClientId:yourSecret" --basic -H "Accept: application/json" --data-urlencode "grant_type=password" --data-urlencode "username=yourUsername" --data-urlencode "password=yourPassword" --data-urlencode "customer_id=yourCustomerId" https://api.optionscity.com/oauth/token

For example, using fake data:

curl -v -u "123456:abcdefg" --basic -H "Accept: application/json" --data-urlencode "grant_type=password" --data-urlencode "username=doug.e.fresh@hotmail.com" --data-urlencode "password=letmein" --data-urlencode "customer_id=9999" https://api.optionscity.com/oauth/token

Note that with the above approach, you do not have to base64 encode your username and password, as the -u command signals cURL to do the encoding for you. It is also not necessary to specify a POST type or to use an explicit header of "Content-Type: application/x-www-form-urlencoded", as these will be automatically inferred by cURL given other parts of the command. Though including the POST command or the explicit Content-Type header will not hurt.

If you prefer to rewrite the above cURL command with a more explicit use of Basic Authorization, you must make sure to encode your clientId:secret string in base64. E.g., curl -v -H "Authorization: Basic *base64encodedVersionOfClientId:Secret*" --data-urlencode "username ...

You can even cURL against your local host if needed. Just make sure you have your user information from the local instance (versus Dev or Prod), and change the url of the cURL, per the following (note that using https won't work for localhost):

curl -v -u "clientIdFromLocalInstance:clientSecretFromLocalInstance" --basic --data-urlencode "grant_type=password" --data-urlencode "password=localInstanceAccountPassword" --data-urlencode "customer_id=localInstanceUserId" http://localhost:9000/oauth/token

Examples

Submitting an Order

For documentation, see https://api.optionscity.com/docs/trading#orderactionspost

This example posts to account 5830 in Dev, and submits a buy-side Limit Order on an ES instrument, good for the day, at price 2548.75.

curl -v -X POST -H "Authorization: Bearer <YourAuthToken>" -H "Accept: application/json" -H "Content-Type:application/json" -d '{"action_type":"LimitOrderSub", "acct_id":5830, "instrument_id":2958910, "side":"Buy", "time_in_force":"Day", "limit_price":2548.75, "quantity":1}' https://devapi.optionscity.com/orderactions

Posting a Balance and Net Liq

For documentation, see https://api.optionscity.com/docs/accounts#accountmoneyvalspost

This example posts to account 5895 in Dev.

curl -v -X POST -H "Authorization: Bearer <YourAuthToken>" -H "Accept: application/json" -H "Content-Type: application/json" -d '{"cash_balance" : 50000, "net_liq" : 65000, "as_of" : "2017-08-10"}' https://devapi.optionscity.com/accounts/5895/moneyvals

Posting a Position

For documentation, see https://api.optionscity.com/docs/positions#refpositionspost

This example posts to account 354 in Dev, using two instruments.

curl -v -X POST -H "Authorization: Bearer <YourAuthToken>" -H "Accept: application/json" -H "Content-Type: application/json" -d '{"position":[{"instrument_id":2451610,"quantity":5,"price":2450.5},{"instrument_id":2876481,"quantity":-2,"price":2500.75}],"acct_id":382,"as_of":"2017-09-12"}' https://devapi.optionscity.com/refpositions

Posting a User

For documentation, see https://api.optionscity.com/docs/users#userspost

This example posts a new user to Dev

curl -v -u "yourClientId:yourSecret" --basic -H "Accept: application/json" -H "Content-Type: application/json" -d '{"email":"first.last@example.com", "first_name":"Faker","last_name":"McTwoShoes","password":"fakePassword", "address" : {"line_1" : "150 S Wacker","line_2" : "Suite 2300","city" : "Chicago","state" : "IL","zip" : "60601","country" : "US"}}' https://devapi.optionscity.com/users

Getting all Orders of a Certain Status

For documentation, see https://api.optionscity.com/docs/orders#ordersget

This example queries Dev for all Open orders. Note that only those orders accessible to the user will be returned.

curl -v -H "Authorization: Bearer <YourAuthToken>" -H "Accept: application/json" -H "Content-Type: application/json" https://devapi.optionscity.com/orders?status="Open"

Getting Market Data

For documentation, see https://api.optionscity.com/docs/marketdata#marketdataget

This example queries Dev for market data on a number of instruments, and specifies the sides of interest.

Note that you want to enclose the url endpoint in quotes so that the query parameters will be parsed correctly. If you leave out the quotes, you will have to include \s to get things working. E.g., https://devapi.optionscity.com/marketdata\?sides\=Last\&instrument_ids\=2062123\&instrument_ids\=2487138

curl -v -H "Authorization: Bearer <YourAuthToken>" -H "Accept: application/json" -H "Content-Type: application/json" "https://devapi.optionscity.com/marketdata?instrument_ids=3755177&instrument_ids=3412356&instrument_ids=2862214&instrument_ids=2681445&instrument_ids=2291662&instrument_ids=2171478&instrument_ids=1946914&instrument_ids=1731267&instrument_ids=1210040&instrument_ids=1210731&instrument_ids=1050671&instrument_ids=690349&instrument_ids=580115&instrument_ids=692559&instrument_ids=174358&instrument_ids=174349&sides=Volume&sides=Low&sides=High&sides=Last&sides=Sell&sides=Buy"

Getting a Product Group by ID

For documentation, see https://api.optionscity.com/docs/productgroups#productgroupsgetid

This example queries Dev for Product Group 25

curl -v -H "Authorization: Bearer <YourAuthToken>" -H "Accept: application/json" -H "Content: application/json" https://devapi.optionscity.com/productgroups/25

Troubleshooting

  • Include the -v flag after "curl" to get verbose logging, which might help narrow down the issue.

  • By default, our API will return HTML. Try including -H "Accept: application/json" as needed.

  • Make sure each part of your cURL statement is preceded with the appropriate flag. E.g., curl -H "Accept: application/json" "Content-Type: application/json will not work, because there needs to be another -H before the "Content-Type ..."

  • Check for authorization problems:

If you see something like this in the verbose output from your curl command

< HTTP/1.1 303 See Other < Date: Thu, 10 Aug 2017 16:56:59 GMT < Location: / < Set-Cookie: optionshop=; Max-Age=0; Expires=Thu, 10 Aug 2017 16:56:59 GMT; Path=/; HTTPOnly < Set-Cookie: PLAY_FLASH=danger=You+must+log+in+to+take+this+action.; Path=/; HTTPOnly

then your cURL command is not setting authorization parts correctly.

In particular, make sure you are not using Basic Authorization for a command that requires a Bearer Token.