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
| Field | Type | Required | Description |
|---|---|---|---|
broker | string | Yes | Broker 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. |
mode | string | No | sandbox for simulated data or live for the real account. Defaults to live when credentials are sent, otherwise sandbox. |
label | string | No | Your own name for this connection, up to 80 characters. |
credentials | object | No | Your own broker API credentials. Required for live mode; leave out for sandbox. Unknown keys are rejected. |
credentials.api_key | string | No | Your broker API key, 1 to 200 characters. |
credentials.api_secret | string | No | Your broker API secret, 1 to 200 characters. |
credentials.access_token | string | No | The broker's access token for today, 1 to 2000 characters. |
credentials.client_id | string | No | Your broker client id, 1 to 100 characters. |
credentials.base_url | string | No | Broker 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
| Field | Type | Description |
|---|---|---|
connection_id | string | Id to pass as connection_id on every other broker call. |
broker | string | The broker this connection is for. |
mode | string | sandbox or live. |
label | string | The connection's label. |
status | string | Always 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.