# Trade on behalf of

## Goal

Execute a spot trade with ESP rates on behalf of another organization, from login and requesting rates to downloading the done trade.

This guide uses the [Get fixed-period market data](/developer-portal/tutorials/tutorialfixedperiodmds) workflow for tradable rates, but you can substitute the [Get spot prices](/developer-portal/tutorials/tutorialgetesp) workflow in Step 2.

## Prerequisites

- Your REST API app.
- Integral API login with trading permission.
- Your organization provisioned with at least one provider who streams ESP spot prices.
- A customer organization that you trade on behalf of.


## Steps

```mermaid
flowchart TD
  LOGIN(Step 1: Login) --> RATES(Step 2: Get market data)
  RATES --> PLACEORDER("Step 3: Place order (previously quoted)")
  QUERYORDER(Step 4: Query order) -->|Poll for order status| QUERYORDER
  PLACEORDER --> QUERYORDER
  QUERYORDER -->|Order status = FILLED| DOWNLOADTRADE(Step 5: Download trade)
  click LOGIN "#step-1-login"
  click RATES "#step-2-get-fixed-period-market-data"
  click PLACEORDER "#step-3-place-an-order-previously-quoted"
  click QUERYORDER "#step-4-query-order"
  click DOWNLOADTRADE "#step-5-download-trade"
```

### Step 1: Login

Use the [Login and get token](/openapi/integral-api-reference/rest/authentication-api/login) endpoint.

See the related [Login](/developer-portal/tutorials/tutorialauth) tutorial.

Your access token is in `SSO_TOKEN` of the response header. Your token is valid for limited time.

Pass the `SSO_TOKEN` cookie value with all of your subsequent API requests.

```json Payload application/json
{
  "user": "apiUserId",
  "pass": "This is a long password!",
  "org": "apiOrganizationId"
}
```

### Step 2: Get fixed-period market data

Use the [Get market data](/openapi/integral-api-reference/rest/market-data/getmarketdataset) endpoint.

Use the `rateId` attribute of the JSON response in the next step.

See the related [Get fixed-period market data](/developer-portal/tutorials/tutorialfixedperiodmds) tutorial.

```javascript JavaScript
const query = new URLSearchParams({
  id: 'string',
  org: 'BNK1-4HOrg',
  symbol: 'EUR/USD',
  symbols: 'EUR/USD,USD/JPY',
  date: '2024-10-24',
  tenor: 'SPOT',
  timeWindow: '1500-1700'
}).toString();

const resp = await fetch(
  `/v2/marketdataset?${query}`,
  {
    method: 'GET',
    headers: {
      SSO_TOKEN: 'YOUR_API_KEY_HERE'
    }
  }
);

const data = await resp.text();
console.log(data);
```

### Step 3: Place an order (previously quoted)

Use the [Place order](/openapi/integral-api-reference/rest/orders/placeorder) endpoint.

See the related [Place an order (previously quoted)](/developer-portal/tutorials/tutorialplaceorderpq) tutorial.

These parameters are required on the request body: `org`, `account`, `coId`, `type`, `side`, `symbol`, `size`, `price`, `currency`, `timeInForce`, `rateId`.

- `rateId` contains the `rateId` from the rate in the market data.
- `org` contains the organization ID of the organization you are trading on behalf of.
- `account` contains the account ID (legal entity) of the behalf-of organization.


To get your order status, you must query your order. After the initial success/fail response to your request, status updates are not pushed to you.

```json Payload application/json
{
  "coId": "pq11233",
  "rateId": "4HProduct|2022-11-14|0800-1200|EURUSD|SPOT",
  "currency": "EUR",
  "size": 9000000,
  "type": "PQ",
  "price": 1.1652,
  "side": "Buy",
  "symbol": "EUR/USD",
  "timeInForce": "FOK"
}
```

### Step 4: Query order

To get your order status, you must query your order. After the initial success/fail response, status updates are not pushed to you.

Use the [Query order (server ID)](/openapi/integral-api-reference/rest/orders/queryorderbyserverid) endpoint.

The diagram shows the values returned in the `status` field in the response.

div
Order status transition (PQ order, success)
```mermaid
stateDiagram-v2
  direction LR
  RECEIVED: Status = RECEIVED\nHTTP code 202
  NEW: Status = NEW\n(Intermediate state)\nHTTP code 200
  FILLED: Status = FILLED\nHTTP code 200
  REJECTED: Status = REJECTED\nHTTP code 200
  [*] --> RECEIVED: Place order
  RECEIVED --> NEW: Query order
  RECEIVED --> REJECTED: Query order
  NEW --> FILLED: Query order
  NEW --> REJECTED: Query order
  FILLED --> [*]
  REJECTED --> [*]
```

div
Order status transition (failure)
```mermaid
stateDiagram-v2
  direction LR
  ERROR: Error object\nHTTP code 400/5xx
  [*] --> ERROR: Place order
  ERROR --> [*]
```

```javascript JavaScript
const id = '4820276016';
const resp = await fetch(
  `/v2/orders/${id}`,
  {
    method: 'GET',
    headers: {
      SSO_TOKEN: 'YOUR_API_KEY_HERE'
    }
  }
);

const data = await resp.text();
console.log(data);
```

### Step 5: Download trade

Use the [Get trades](/openapi/integral-api-reference/rest/stp-download/gettrades) endpoint.

The endpoint returns all executed trades that have not been downloaded before.

Use the `orderId` from the 202 response when you placed the order to find your trade in the array of returned trades.

```javascript JavaScript
const query = new URLSearchParams({maxCount: '20'}).toString();

const resp = await fetch(
  `/v2/trades/stp/messages?${query}`,
  {
    method: 'GET',
    headers: {
      SSO_TOKEN: 'YOUR_API_KEY_HERE'
    }
  }
);

const data = await resp.text();
console.log(data);
```