API reference / Depository / Broker

Connect LIVE account (real data)

Pass your own broker API credentials to get REAL holdings/orders. Groww: token from groww.in → Settings → Trading APIs. Dhan: web.dhan.co. Credentials are vault-encrypted.

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

Before you integrate

  • Sending credentials links the real account, so holdings, orders and funds are real. Live mode without credentials is refused.
  • Credentials are stored encrypted and never returned. Brokers issue a new access token each day; replace it with the token rotate call.

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": "groww",
  "credentials": {
    "access_token": "PASTE_YOUR_GROWW_ACCESS_TOKEN"
  }
}'

Sample response

{
  "request_id": "req_01HZY3K8M2",
  "result": {
    "connection_id": "bconn_c3d4e5f607182930",
    "broker": "groww",
    "mode": "live",
    "label": "groww (live)",
    "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.