# 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.wingmantracker.com/api-documentation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.