# API Documentation

You can use our API to access Wingman user's position data, enabling you to build additional features and improvements on top of our foundation.

This API is very simple for now and only fetches information (GETs). As in, there is currently no write access (POST) to Wingman.

**For a given user, it can return:**

* full open positions hierarchy (position --> legs --> transactions)
* closed positions (with filters)

More endpoints will be added according to demand, so please reach out with requests by emailing <ben@wingmantracker.com>.

## Authentication

Wingman uses API Keys and User Tokens to allow access to the API. Each User requests a key that can only be used for your application. You can create a Personal API Key and Token on the [Wingman Settings page](https://app.wingmantracker.com/settings).

And to register your application for any Wingman user to use, please email <ben@wingmantracker.com>.

## Ping Test

<mark style="color:blue;">`GET`</mark> `https://app.wingmantracker.com/api/v1/`&#x20;

Check to see if your API Key and User Token is valid and that the API is responding.

#### Query Parameters

| Name     | Type   | Description            |
| -------- | ------ | ---------------------- |
| api\_key | string | Your Developer API Key |

#### Headers

| Name           | Type   | Description                                                                               |
| -------------- | ------ | ----------------------------------------------------------------------------------------- |
| Authentication | string | <p>The User's Token for your application. <br>Format is "Bearer insert\_user\_token".</p> |

{% tabs %}
{% tab title="200 API Key and User Token are valid." %}

```javascript
"You're in."
```

{% endtab %}

{% tab title="401 " %}

```javascript
// If your API Key is invalid.
"Application API Key is invalid."

// If your API Key is valid but User Token is invalid.
"Not a valid user token.
```

{% endtab %}
{% endtabs %}

## Fetching User Data

## Open Positions

<mark style="color:blue;">`GET`</mark> `https://app.wingmantracker.com/api/v1/open_positions`

This endpoint retrieves all Open Positions with their nested entities (Position --> Legs --> Transactions).

#### Query Parameters

| Name     | Type   | Description            |
| -------- | ------ | ---------------------- |
| api\_key | string | Your Developer API Key |

#### Headers

| Name           | Type   | Description                                                                              |
| -------------- | ------ | ---------------------------------------------------------------------------------------- |
| Authentication | string | <p>The User's Token for your application.<br>Format is "Bearer insert\_user\_token".</p> |

{% tabs %}
{% tab title="200 An array of Positions, which contain Legs, which contain Transactions (nested hierarchy)." %}

```javascript
[
  {
    "underlying": "XYZ",
    "id": 1,
    "strategy": "Strangle (Short)",
    "strikes": "100/105",
    "current_expiration_date": "2020-01-01",
    "notes": "string or null",
    "original_basis": -1.0,
    "current_basis": -1.0,
    "amount": 100.00,
    "realized_pl": -2.0,
    "is_open": true,
    "account": {
      "id": 1,
      "name": "string"
    },
    "quantity": -1,
    "decimal_places": 2,
    "group_tags": [
      {
        "id": 1,
        "name": "string"
      },
    ],
    "legs": [
      {
        "id": 1,
        "symbol": "XYZ_010120P100",
        "quantity": -1.0,
        "expiration_date": "2020-01-01",
        "original_basis": 0.50,
        "current_basis": 0.50,
        "strike": 100,
        "amount": 50.0,
        "realized_pl": -1.0,
        "transactions": [
          {
            "id": 1,
            "entry_date": "2019-12-01T19:24:40.000Z",
            "quantity": -1.0,
            "price": 0.50,
            "amount": 50.0,
            "order_action": "SELL_TO_OPEN",
            "instrument": "PUT",
            "commission_and_fees": -1.0,
            "created_at": "2019-12-02T19:24:40.000Z"
          },
        ]
      },
    ]
  },
]
```

{% endtab %}
{% endtabs %}

## Closed Positions

<mark style="color:blue;">`GET`</mark> `https://app.wingmantracker.com/api/v1/closed_positions`

This endpoint retrieves all Closed Positions for a user. It can potentially be a lot of data because it's the entire history in Wingman for that user, so you are encouraged to use filters.\
\
You can submit multiple filters and they will be combined via AND condition. For example, specify a starting\_entry\_date and ending\_entry\_date will give you the expected date range.

#### Query Parameters

| Name                  | Type    | Description                                                                    |
| --------------------- | ------- | ------------------------------------------------------------------------------ |
| api\_key              | string  | Your Developer API Key                                                         |
| ending\_close\_date   | string  | Return closed positions that were closed before this date. YYYY-MM-DD format.  |
| starting\_close\_date | string  | Return closed positions that were closed after this date. YYYY-MM-DD format.   |
| ending\_entry\_date   | string  | Return closed positions that were entered before this date. YYYY-MM-DD format. |
| starting\_entry\_date | string  | Return closed positions that were entered after this date. YYYY-MM-DD format.  |
| account\_id           | integer | Return closed positions that are in the specified account.                     |

#### Headers

| Name           | Type   | Description                                                                              |
| -------------- | ------ | ---------------------------------------------------------------------------------------- |
| Authentication | string | <p>The User's Token for your application.<br>Format is "Bearer insert\_user\_token".</p> |

{% tabs %}
{% tab title="200 An array of Positions. No hierarchy like in Open Positions." %}

```javascript
[
  {
    "underlying": "string",
    "id": 1,
    "strategy": "string",
    "entry_date": "2019-12-02T19:24:40.000Z",
    "close_date": "2019-12-03T19:24:40.000Z",
    "original_expiration_date": "2020-01-01",
    "original_dte": 30,
    "original_cost": -10.0,
    "days_in_trade": 1,
    "notes": "string or null",
    "realized_pl": 1.0,
    "fees": -1.0,
    "is_open": false,
    "account": {
      "id": 1, 
      "name": "string"
    },
    "decimal_places": 2,
    "group_tags": [
      {
        "id": 1,
        "name": "string"
      },
    ],
    "num_transactions": 2,
    "dividends": 0.00
  }
]
```

{% endtab %}
{% endtabs %}