Quick Trade

The Quick Trade tool in Eclipse creates buy or sell orders for an account. You can also upload a spreadsheet to create buys and sells across many accounts, including lot-level (VSP) sells that target a specific tax lot.

This guide walks through each API call in order. You only need one workflow per job — pick it from the table below, then jump to that section.

Before you start

• Authenticate first. You need an Eclipse token on every request. See Generating an Eclipse Token.
• Send that token in the Authorization header (for example, Bearer YOUR_TOKEN).
• Replace the host in the examples with your Eclipse API host. Paths in this guide start at /api/…
• You will need Eclipse IDs: accountId (eclipse internal account id), portfolioId (portfolio that owns the account), and for buy/sell, securityId (the product to trade). Account number is the number you see in Eclipse / at the custodian — file import can use either account id or account number. See Search Eclipse Account.

In the examples, POST means “send this data to Eclipse and do the work.” Most requests send JSON (Content-Type: application/json). File upload is the exception: that request sends the file as form data.

Which workflow should I use?

What you want to do	Use
Buy or sell one security in one account	Workflow 1 — Single account buy or sell
Liquidate (sell out) one account	Workflow 2 — Account liquidation
Create many buys/sells from a spreadsheet, including sells of a specific tax lot (VSP)	Workflow 3 — File import

Buy, sell, and liquidate use different API versions on purpose. Use the endpoint in the workflow you chose — do not mix them.

Workflow 1 — Single account buy or sell

Use this when you already know the account, the security, the action (buy or sell), and the size of the trade (shares, dollars, or percent).

1. (Optional) Validate the trade so you can see warnings before you create an order.
2. Create the order.

Validation does not create an order. If you skip it, create still validates again before saving.

Step 1 (optional) — Validate the trade

The validate endpoint is used by several Eclipse trade tools. For Quick Trade, send application as “QuickTrades” and one or more trades in the trades array.

This step is for buy and sell only. It is not used for liquidation or for file import (file import validates when you upload the file).

POST api/v2/tradeorder/trades/action/validate

Name	Type	Required	Description
application	string	yes	Must be “QuickTrades” for this workflow.
action	number	yes	1 = Buy, 2 = Sell
tradeShares	number	no*	Number of shares to trade. Fractional shares depend on custodian configuration.
tradePercent	number	no*	Percent of the current holding. Sell trades only.
tradeAmount	number	no*	Dollar amount to trade.
accountId	number	yes	Eclipse id of the account being traded.
portfolioId	number	no	Eclipse id of the portfolio that contains the account.
securityId	number	yes	Eclipse id of the security being traded.
symbol	string	no	Ticker of the security (for example AAPL). Helpful for readability; securityId is what Eclipse uses.

Example request

{
    "application": "QuickTrades",
    "trades": [
        {
            "action": 1,
            "tradeShares": null,
            "tradePercent": null,
            "tradeAmount": 2100.57,
            "accountId": 127,
            "portfolioId": 227,
            "securityId": 13,
            "symbol": "AAPL"
        }
    ]
}

Read the response for each item in trades. If something is wrong, Eclipse explains it in warningMessage and/or error. Fix the request and validate again, or go on to create if you are satisfied.

Step 2 — Create the buy or sell order

This is the V2 create call. It saves the order(s) in Eclipse. Send the same trade fields you validated, plus application.

POST api/v2/tradeorder/trades

Name	Type	Required	Description
application	string	yes	Must be “QuickTrades”.
action	number	yes	1 = Buy, 2 = Sell
portfolioId	number	yes	Eclipse id of the portfolio being traded.
accountId	number	yes	Eclipse id of the account being traded.
tradeShares	number	no*	Number of shares to trade.
tradePercent	number	no*	Percent of the current holding. Sell trades only.
tradeAmount	number	no*	Dollar amount to trade.
securityId	number	yes	Eclipse id of the security being traded.
tradeToolSelection	number	no**	2 = Account
tradeInstanceType	number	no**	5 = Quick Trade
tradeInstanceSubType	number	no**	11 = Quick Trade

Example request (minimum)

{
    "application": "QuickTrades",
    "trades": [
        {
            "action": 1,
            "portfolioId": 227,
            "accountId": 127,
            "tradeShares": null,
            "tradePercent": null,
            "tradeAmount": 2100.57,
            "securityId": 13
        }
    ]
}

Example request (with recommended Trade Instance labels)

{
    "application": "QuickTrades",
    "trades": [
        {
            "action": 1,
            "portfolioId": 227,
            "accountId": 127,
            "tradeShares": null,
            "tradePercent": null,
            "tradeAmount": 2100.57,
            "securityId": 13
        }
    ],
    "tradeToolSelection": 2,
    "tradeInstanceType": 5,
    "tradeInstanceSubType": 11
}

A successful response includes a Trade Instance id and the new trade id(s). If a row cannot be created, it is listed with the reason (for example a trading restriction). Use the instance id to find the orders in Eclipse.

Workflow 2 — Account liquidation

Use this to liquidate one account (sell holdings in that account). Liquidation uses the V1 endpoint, not the V2 buy/sell endpoint above.

POST api/v1/tradeorder/trades

Name	Type	Required	Description
accountId	number	yes	Eclipse id of the account being liquidated.
portfolioId	number	no	Eclipse id of the portfolio being traded.
actionId	number	yes	6 = Liquidate
tradeToolSelection	number	no**	2 = Account
tradeInstanceType	number	no**	5 = Quick Trade
tradeInstanceSubType	number	no**	11 = Quick Trade

Example request

{
    "accountId": 127,
    "portfolioId": 227,
    "actionId": 6,
    "tradeToolSelection": 2,
    "tradeInstanceType": 5,
    "tradeInstanceSubType": 11
}

Workflow 3 — File import (many accounts, including VSP)

Use this when you have a list of buys and sells across accounts. This is also the only Quick Trade API flow that can target a specific tax lot (a lot-level, or VSP, sell).

VSP means versus purchase: sell shares from a specific tax lot (the lot you bought on a given date at a given cost) instead of letting the custodian choose which lots to sell.

File import is always two steps, in this order:

1. Upload the file. Eclipse reads the rows and validates them. Nothing is traded yet.
2. Send the valid rows from that response back to Eclipse to create the orders.

Do not send the spreadsheet to the validate or create endpoints (workflow 1). Do not skip step 1 and invent the step 2 body by hand if you need VSP — lot matching happens in step 1.

Prepare the file

Use .xlsx, .xls, or .csv. Put a header row first. Column names are not case-sensitive, and spaces are optional (Account Id and AccountId both work; Ticker and Symbol both work).

Column	Required	What to put in it
Account Id	yes*	Eclipse account id. Use this or Account Number — not both. If both are filled, Eclipse cannot resolve the account.
Account Number	yes*	Account number as shown in Eclipse. Use this or Account Id — not both.
Action	yes	Buy or Sell (any capitalization).
Ticker	yes	Security symbol, for example AAPL.
Dollars	no**	Dollar amount to trade.
Shares	no**	Share quantity. For a full sell you may enter ALL, SELL ALL, SA, or S A instead of a number (100% of the position). A 100% sell is never a lot-level / VSP trade.
Acquired Date	no***	Lot-level (VSP) sells only. The purchase date of the tax lot to sell. Examples: 01/15/2020, 01-15-2020, 2020-01-15. Leave blank on buys and on normal sells.
Cost Per Share	no***	Lot-level (VSP) sells only. Cost per share of that tax lot. Must be sent together with Acquired Date. Leave blank on buys and on normal sells.

Sample CSV

Account Number	Action	Ticker	Dollars	Shares	Acquired Date	Cost Per Share
Test04	Sell	AAPL	700
Test10	Sell	ARKX		10	01/15/2020	12.345
Test15	Buy	HD	800

Row 1 is a normal sell (no lot specified). Row 2 is a VSP sell of 10 shares of ARKX from the lot bought on 15 Jan 2020 at 12.3456 per share. Row 3 is a buy; lot columns are ignored even if you filled them in.

How VSP matching works

When a sell has both Acquired Date and Cost Per Share, Eclipse looks for a tax lot in that account and security that matches:

• the same acquired date (time of day is ignored), and
• the same cost per share, compared after rounding to 4 decimal places.

If it finds a match, the response includes that lot’s taxLotId and sets forceVsp to true. That forces a lot-level sell even if the account’s VSP preference is off. If several lots share the same date and cost, Eclipse prefers a lot with enough quantity for the sell.

If no lot matches, that row is invalid: “The position does not have a matching lot.”

Step 1 — Upload the file (validate)

POST api/v2/tradeorder/uploadfile

This is not JSON. Send the file as multipart/form-data on a form field named document.

Example (curl)

curl -X POST "https://{eclipse-api-host}/api/v2/tradeorder/uploadfile" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "document=@quick-trades.csv"

Read the JSON response before you continue.

If portfolios need analytics — stop. Run analytics on those portfolios, then upload again. You cannot create trades until this is cleared.

{
    "portfolioFlag": [
        {
            "portfolioId": 227,
            "needAnalytics": true,
            "failedReason": null
        }
    ],
    "trades": null
}

If you get a trades array — each row has isValid. Only rows with isValid true can be created. Invalid rows include a warningMessage explaining why.

For a successful VSP sell, keep the extra fields Eclipse added. You will send them back in step 2:

• taxLotId — the matched lot
• forceVsp / isVsp — marks the trade as lot-level
• dateAcquired and costPerShare — the values that were matched

Example valid VSP row in the upload response (other fields omitted)

{
    "portfolioFlag": null,
    "trades": [
        {
            "accountId": 127,
            "accountNumber": "Tact10",
            "portfolioId": 227,
            "securityId": 13,
            "symbol": "ARKX",
            "action": 2,
            "tradeShares": 10,
            "dateAcquired": "2020-01-15T00:00:00",
            "costPerShare": 12.3456,
            "taxLotId": 999,
            "forceVsp": true,
            "isVsp": true,
            "isValid": true,
            "warningMessage": ""
        }
    ]
}

Note: in the file, Action is the text Buy or Sell. In the JSON response, action is a number (1 = Buy, 2 = Sell). Send the JSON values back in step 2, not the spreadsheet text.

Step 2 — Create orders from the valid rows

POST api/v2/tradeorder/uploadTrades

Content-Type: application/json.

Easiest approach: copy the trades array from the upload response, remove every item where isValid is not true, and send those objects back unchanged. That preserves VSP fields. Lot matching is not run again on this call.

Name	Type	Required	Description
tradesAreAlreadyValidated	boolean	yes	Set to true. You already validated in step 1.
trades	array	yes	Only valid rows from the upload response. For VSP sells, keep taxLotId, forceVsp, dateAcquired, and costPerShare.
instanceNotes	string	no	Optional notes stored on the Trade Instance.

You do not send application or the Trade Instance label fields on this request. Eclipse records the instance as a Quick Trade created from an Excel import (selection 6, type 5, subtype 17).

Example request

{
    "tradesAreAlreadyValidated": true,
    "instanceNotes": "Q3 lot-level sell import",
    "trades": [
        {
            "accountId": 127,
            "portfolioId": 227,
            "securityId": 13,
            "symbol": "ARKX",
            "action": 2,
            "tradeShares": 10,
            "dateAcquired": "2020-01-15T00:00:00",
            "costPerShare": 12.3456,
            "taxLotId": 999,
            "forceVsp": true,
            "isVsp": true,
            "isValid": true
        }
    ]
}

A successful response includes the new Trade Instance id and created trade ids. Rows that fail a later check (preferences, restrictions, and so on) are returned as excluded trades with a reason.

Common import messages

Message	What it usually means	What to do
Either an AccountId or AccountNumber is required.	That row has neither identifier.	Fill Account Id or Account Number.
The provided Account does not exist.	The id or number did not match an account.	Correct the identifier. Do not send both columns.
The provided Account is SMA.	SMA accounts are not importable for this firm.	Remove the row or use a non-SMA account.
Account is Disabled.	The account is disabled.	Enable the account or remove the row.
Either Dollars or Shares is required.	No usable quantity on the row.	Enter a number in Dollars or Shares.
Security data for {ticker} is not valid. / Price for {ticker} is not valid.	Eclipse could not use that symbol or its price.	Check the ticker and that the security is priced.
Acquired Date is required. / Cost Per Share is required.	A VSP sell has only one of the two lot columns.	Provide both, or clear both for a normal sell.
Acquired Date […] is not a valid date. / Cost Per Share […] is not a valid number.	The lot value could not be parsed.	Use a real date and a numeric cost.
The position does not have a matching lot.	No tax lot matched account + security + date + cost.	Confirm the lot exists and that date/cost match (cost is compared at 4 decimals).

Trade Instance metadata (optional)

A Trade Instance is the “batch” Eclipse creates when you generate trades: it groups the orders and shows which tool created them. The fields below are optional labels for that batch. They do not change how the trade is calculated.

Use the values that match what you actually did, so the instance looks correct in the Eclipse UI. Do not label a Quick Trade as if it came from another tool. Full lists are in Trade Instance Fields.

Recommended labels:

Workflow	tradeToolSelection	tradeInstanceType	tradeInstanceSubType
Single-account buy, sell, or liquidation	2 (Account)	5 (Quick Trade)	11 (Quick Trade)
File import	Do not send these. Eclipse sets 6 (Excel Import), 5 (Quick Trade), 17 (Trade Import).