API reference / Depository / Broker

Unified broker connect

Link a broker account — 13 brokers behind one contract, the broker is just a parameter. Sandbox needs no credentials.

POST/v1/broker/connect
Authentication
Bearer token
Scope
broker:write

Before you integrate

  • Connect first, then pass connection_id to every other broker call. Sandbox needs no credentials and returns simulated data.
  • Live mode uses your own broker API credentials. They are stored encrypted and never returned.
  • Brokers issue a new access token each day; replace it with the token rotate call.
  • Brokers that offer a hosted login can be linked with login start and login callback instead of sending credentials.

Request body

FieldTypeRequiredDescription
brokerstringYesBroker name, 2 to 30 characters. One of: zerodha, angel, dhan, upstox, groww, motilal, fyers, shoonya, flattrade, xts, zebu, tradesmart, arrow. Common short names such as kite or angelone are also accepted.
modestringNosandbox for simulated data or live for the real account. Defaults to live when credentials are sent, otherwise sandbox.
labelstringNoYour own name for this connection, up to 80 characters.
credentialsobjectNoYour own broker API credentials. Required for live mode; leave out for sandbox. Unknown keys are rejected.
credentials.api_keystringNoYour broker API key, 1 to 200 characters.
credentials.api_secretstringNoYour broker API secret, 1 to 200 characters.
credentials.access_tokenstringNoThe broker's access token for today, 1 to 2000 characters.
credentials.client_idstringNoYour broker client id, 1 to 100 characters.
credentials.base_urlstringNoBroker host URL, up to 300 characters; only for brokers on the xts platform.

Sample code

Set your key in the GRAPPI_API_KEY environment variable. Sample values are placeholders.

curl -sS -X POST 'https://grappi.ai/v1/broker/connect' \
  -H "Authorization: Bearer $GRAPPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "broker": "zerodha"
}'

Sample response

{
  "request_id": "req_01HZY3K8M2",
  "result": {
    "connection_id": "bconn_a1b2c3d4e5f60718",
    "broker": "zerodha",
    "mode": "sandbox",
    "label": "zerodha (sandbox)",
    "status": "connected"
  }
}

Response fields

FieldTypeDescription
connection_idstringId to pass as connection_id on every other broker call.
brokerstringThe broker this connection is for.
modestringsandbox or live.
labelstringThe connection's label.
statusstringAlways connected on success.

Errors

Every failure has the same shape. A call that fails on our side or at the data source is refunded to your wallet; a "no record found" answer is charged. See the error reference.