GTT orders

Good-till-triggered orders the broker holds for you.

List GTTs #

GET /v1/gtt scope read

Every GTT at the broker, per account (a live read, including GTTs made outside this API; source broker).

More about this

Brokers that place GTTs but cannot list them, or whose list read failed where that read is best-effort (Pocketful, whose list reply is undocumented), are listed from this API's own records instead (source api_records): the GTTs placed through this API and not deleted here, with a note saying why and that GTTs placed outside it are not visible. An account whose list cannot be read carries an error; the others are still listed. Brokers without GTTs carry error_code not_supported_by_broker.

Parameters

account query · string

Only this account; every account when absent.

Errors

HTTP	Code	When
400	invalid_query	The query string does not fit the route's parameters.
401	unauthorized	No credential, or the credential is invalid, expired or revoked.
403	forbidden	The credential may not use this route (missing scope, app-session-only route, IP not allowed).
404	account_not_found	No linked broker account with this id for the caller.
429	rate_limited	Too many requests for this credential (or too many failed attempts); retry after the `Retry-After` header (seconds; `error.retry_after_ms` has the exact wait).
503	service_unavailable	A dependency is temporarily unavailable, or the feature is off on this server; retry later.

All fields (request and response schema)

Loading fields…

GET

curl "https://cirrus.pocketful.in/v1/gtt" \
  -H "Authorization: token $CIRRUS_API_KEY"

import os

import requests

response = requests.get(
    "https://cirrus.pocketful.in/v1/gtt",
    headers={
        "Authorization": f"token {os.environ['CIRRUS_API_KEY']}",
    },
    timeout=10,
)
print(response.status_code, response.json())

const response = await fetch('https://cirrus.pocketful.in/v1/gtt', {
  method: 'GET',
  headers: {
    Authorization: `token ${process.env.CIRRUS_API_KEY}`,
  },
});
const body = await response.json();
console.log(response.status, body);

Response · 200

{
  "status": "success",
  "data": [
    {
      "account": "U1",
      "broker": "upstox",
      "source": "broker",
      "gtts": [],
      "note": null,
      "error": "Listing GTTs is not available for upstox accounts.",
      "error_code": "not_supported_by_broker"
    }
  ],
  "error": null
}

Create a GTT #

POST /v1/gtt scope orders

Creates a GTT at the broker in one account: a stop-loss, a target, or both (whichever fires first cancels the other).

More about this

Legs are checked against the tick grid and the live price. Once the request is valid the answer is 200 with the broker's verdict in status.

Broker limits: Pocketful has no GTT on BFO (and CDS) or on intraday (MIS) products. These, and brokers without GTT at all, come back as rejected with error_code not_supported_by_broker (nothing was sent to the broker).

Body fields

account string required

Account id (see /v1/accounts).
instrument_token string required

Instrument id (see /v1/instruments).
side string required

Side of the order a trigger places (SELL to protect a long).

One of: BUY, SELL
product string required

MIS (intraday), CARRYFORWARD (overnight derivatives, NRML), DELIVERY (equity delivery, CNC) or MTF (margin trading facility).

One of: MIS, CARRYFORWARD, DELIVERY, MTF
quantity integer (int64) required

Units, or lots when qty_is_in_lot. Units round down to whole lots; under one lot is refused.
qty_is_in_lot boolean

quantity counts lots, not units.
stop_loss object | null

One GTT leg: the price that fires it and the order's limit price.
target object | null

One GTT leg: the price that fires it and the order's limit price.

Errors

HTTP	Code	When
400	malformed_json	The body is not JSON, or does not fit the request shape (unknown or missing fields, wrong types).
401	unauthorized	No credential, or the credential is invalid, expired or revoked.
403	forbidden	The credential may not use this route (missing scope, app-session-only route, IP not allowed).
404	account_not_found	No linked broker account with this id for the caller.
422	invalid_request	The request is well-formed but not valid; `field` names the input.
429	rate_limited	Too many requests for this credential (or too many failed attempts); retry after the `Retry-After` header (seconds; `error.retry_after_ms` has the exact wait).
503	service_unavailable	A dependency is temporarily unavailable, or the feature is off on this server; retry later.

All fields (request and response schema)

Loading fields…

POST

curl -X POST "https://cirrus.pocketful.in/v1/gtt" \
  -H "Authorization: token $CIRRUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account": "PF1",
    "instrument_token": "CT:TEST:RELIANCE",
    "side": "SELL",
    "product": "DELIVERY",
    "quantity": 5,
    "stop_loss": {
      "trigger": 2400,
      "price": 2399
    }
  }'

import os

import requests

response = requests.post(
    "https://cirrus.pocketful.in/v1/gtt",
    headers={
        "Authorization": f"token {os.environ['CIRRUS_API_KEY']}",
    },
    json={
        "account": "PF1",
        "instrument_token": "CT:TEST:RELIANCE",
        "side": "SELL",
        "product": "DELIVERY",
        "quantity": 5,
        "stop_loss": {
            "trigger": 2400,
            "price": 2399,
        },
    },
    timeout=10,
)
print(response.status_code, response.json())

const response = await fetch('https://cirrus.pocketful.in/v1/gtt', {
  method: 'POST',
  headers: {
    Authorization: `token ${process.env.CIRRUS_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "account": "PF1",
    "instrument_token": "CT:TEST:RELIANCE",
    "side": "SELL",
    "product": "DELIVERY",
    "quantity": 5,
    "stop_loss": {
      "trigger": 2400,
      "price": 2399
    }
  }),
});
const body = await response.json();
console.log(response.status, body);

Response · 200

{
  "status": "success",
  "data": {
    "account": "PF1",
    "trigger_id": "0f6c1a52-4d7e-4b8e-9d51-2c7a9e3b1f20",
    "status": "accepted",
    "message": null,
    "error_code": null
  },
  "error": null
}

Modify a GTT #

PATCH /v1/gtt/{trigger_id} scope orders

Replaces a GTT's legs and quantity at the broker: send the GTT as it should be now (same body and checks as creating).

More about this

Once the request is valid the answer is 200 with the broker's verdict in status.

Parameters

trigger_id path · string required

The broker's GTT id (1-64 letters, digits, -, _ or .).

Body fields

account string required

Account id (see /v1/accounts).
instrument_token string required

Instrument id (see /v1/instruments).
side string required

Side of the order a trigger places (SELL to protect a long).

One of: BUY, SELL
product string required

MIS (intraday), CARRYFORWARD (overnight derivatives, NRML), DELIVERY (equity delivery, CNC) or MTF (margin trading facility).

One of: MIS, CARRYFORWARD, DELIVERY, MTF
quantity integer (int64) required

Units, or lots when qty_is_in_lot. Units round down to whole lots; under one lot is refused.
qty_is_in_lot boolean

quantity counts lots, not units.
stop_loss object | null

One GTT leg: the price that fires it and the order's limit price.
target object | null

One GTT leg: the price that fires it and the order's limit price.

Errors

HTTP	Code	When
400	malformed_json	The body is not JSON, or does not fit the request shape (unknown or missing fields, wrong types).
401	unauthorized	No credential, or the credential is invalid, expired or revoked.
403	forbidden	The credential may not use this route (missing scope, app-session-only route, IP not allowed).
404	account_not_found	No linked broker account with this id for the caller.
422	invalid_request	The request is well-formed but not valid; `field` names the input.
429	rate_limited	Too many requests for this credential (or too many failed attempts); retry after the `Retry-After` header (seconds; `error.retry_after_ms` has the exact wait).
503	service_unavailable	A dependency is temporarily unavailable, or the feature is off on this server; retry later.

All fields (request and response schema)

Loading fields…

PATCH

curl -X PATCH "https://cirrus.pocketful.in/v1/gtt/<trigger_id>" \
  -H "Authorization: token $CIRRUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account": "PF1",
    "instrument_token": "CT:TEST:RELIANCE",
    "side": "SELL",
    "product": "DELIVERY",
    "quantity": 5,
    "stop_loss": {
      "trigger": 2420,
      "price": 2419
    }
  }'

import os

import requests

response = requests.patch(
    "https://cirrus.pocketful.in/v1/gtt/<trigger_id>",
    headers={
        "Authorization": f"token {os.environ['CIRRUS_API_KEY']}",
    },
    json={
        "account": "PF1",
        "instrument_token": "CT:TEST:RELIANCE",
        "side": "SELL",
        "product": "DELIVERY",
        "quantity": 5,
        "stop_loss": {
            "trigger": 2420,
            "price": 2419,
        },
    },
    timeout=10,
)
print(response.status_code, response.json())

const response = await fetch('https://cirrus.pocketful.in/v1/gtt/<trigger_id>', {
  method: 'PATCH',
  headers: {
    Authorization: `token ${process.env.CIRRUS_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "account": "PF1",
    "instrument_token": "CT:TEST:RELIANCE",
    "side": "SELL",
    "product": "DELIVERY",
    "quantity": 5,
    "stop_loss": {
      "trigger": 2420,
      "price": 2419
    }
  }),
});
const body = await response.json();
console.log(response.status, body);

Response · 200

{
  "status": "success",
  "data": {
    "account": "PF1",
    "trigger_id": "0f6c1a52-4d7e-4b8e-9d51-2c7a9e3b1f20",
    "status": "accepted",
    "message": null,
    "error_code": null
  },
  "error": null
}

Delete a GTT #

DELETE /v1/gtt/{trigger_id} scope orders

Deletes a GTT at the broker.

More about this

Once the request is valid the answer is 200 with the broker's verdict in status.

Parameters

trigger_id path · string required

The broker's GTT id (1-64 letters, digits, -, _ or .).
account query · string required

Account id the GTT is in.

Errors

HTTP	Code	When
400	invalid_query	The query string does not fit the route's parameters.
401	unauthorized	No credential, or the credential is invalid, expired or revoked.
403	forbidden	The credential may not use this route (missing scope, app-session-only route, IP not allowed).
404	account_not_found	No linked broker account with this id for the caller.
422	invalid_request	The request is well-formed but not valid; `field` names the input.
429	rate_limited	Too many requests for this credential (or too many failed attempts); retry after the `Retry-After` header (seconds; `error.retry_after_ms` has the exact wait).
503	service_unavailable	A dependency is temporarily unavailable, or the feature is off on this server; retry later.

All fields (request and response schema)

Loading fields…

DELETE

curl -X DELETE "https://cirrus.pocketful.in/v1/gtt/<trigger_id>?account=<account>" \
  -H "Authorization: token $CIRRUS_API_KEY"

import os

import requests

response = requests.delete(
    "https://cirrus.pocketful.in/v1/gtt/<trigger_id>",
    headers={
        "Authorization": f"token {os.environ['CIRRUS_API_KEY']}",
    },
    params={
        "account": "<account>",
    },
    timeout=10,
)
print(response.status_code, response.json())

const response = await fetch('https://cirrus.pocketful.in/v1/gtt/<trigger_id>?account=<account>', {
  method: 'DELETE',
  headers: {
    Authorization: `token ${process.env.CIRRUS_API_KEY}`,
  },
});
const body = await response.json();
console.log(response.status, body);

Response · 200

{
  "status": "success",
  "data": {
    "account": "PF1",
    "trigger_id": "0f6c1a52-4d7e-4b8e-9d51-2c7a9e3b1f20",
    "status": "accepted",
    "message": null,
    "error_code": null
  },
  "error": null
}