Try Demo
Start typing to search…

Holdings Import v2 📃

With Holdings Import, you can easily import the latest snapshot of a user’s security (stock and ETF) and smallcase holdings on your platform.

What's new? ✨

smallcase Gateway now provides a new format for the holdings import flow:

  1. Positions are shown separately at an NSE and BSE level since cross-exchange trading is not allowed by most brokers on the same day.
  2. BSE-only listed holdings are being shown in v2 along with an average price that is being picked up from the broker itself.
  3. The transactable quantity is NSE holdings + the NSE positions. This is being shared because users might have BSE positions that are not tradable via smallcase Gateway. Moreover, the user can hold a quantity in smallcases that the user might / might not want to sell.
  4. Names of stocks are shared along with the NSE and BSE tickers.
  5. The quantity of stocks invested via smallcases is available as a new field since the user might/might not want to sell.

Implementation details 🚀

The user flow for holdings import remains the same. The implementation change is in the request parameters of the following APIs:

  1. Create transaction: holdings import

    To create a transactionId for triggering the holdings import in the v2 format, pass the body params as mentioned below:

    {
   "intent": "HOLDINGS_IMPORT",
   "version": "v2"
}

  2. Fetch holdings API

    To fetch the holdings response in the v2 format, pass the query param ?version=v2 in the request URL.

Response Structure 💁

With the new v2 format, the structure of securities and smallcases array have been revamped:

  • securities[]: array of objects with each element representing a stock/ETF holding of the user

    • holdings: represents the stock information for the demat holding

      • quantity: holdings quantity
      • averagePrice: average buy price of the stock holdings

    • positions: represents the information about the positions of the stock

      • nse: positions under the exchange NSE
        • quantity: net quantity under the NSE positions (net quantity here represents buyPositions - sellPositions)
        • averagePrice: net average price for the NSE positions
      • bse: positions under the exchange BSE
        • quantity: net quantity under the BSE positions (net quantity here represents buyPositions - sellPositions)
        • averagePrice: net average price for the BSE positions

    • smallcaseQuantity: represents the quantity of the stock, which belongs to any invested smallcase

    • transactableQuantity: represents the quantity of the stock, which is transactable via smallcase (Note: transactableQuantity also includes the stock quantity that is part of the user's smallcase investment)

    • collateralQuantity: represents the quantity of the stock, held in the user's Demat account for which the user has a loan offered by a stockbroker against the shares

    • nseTicker: ticker symbol for the stock on the NSE

    • bseTicker: ticker symbol for the stock on the BSE

    • isSuspendedOrDelistedOnNSE: flag that denotes whether the stock is suspended or delisted on NSE

    • isSuspendedOrDelistedOnBSE: flag that denotes whether the stock is suspended or delisted on BSE

    • isin: ISIN of the stock

    • name: stock name

  • smallcases: object containing details about the user's smallcase investments

    • public[]: array of public smallcases that the user has invested in

      • scid: the unique identifier of the smallcase
      • name: smallcase name
      • investmentDetailsURL: smallcase platform URL of user's investment details page
      • shortDescription: description of the smallcase
      • imageUrl: smallcase logo URL
      • stats: investment stats
        • currentValue: current market value of the smallcase
        • totalReturns: total returns of the smallcase
      • constituents[]: array of constituents that are part of the user's investment
        • ticker: NSE ticker of the constituent
        • shares: quantity of tickers that are part of this smallcase

    • private: object containing details about the user's investment in private (fee-based) smallcases

      • stats: an object containing overall stat's about user combined private smallcase investment
        • currentValue: aggregated current market value of investments in all fee-based smallcases combined
        • totalReturns: aggregated total returns of investments in all fee-based smallcases combined

Sample response 📃

{
  "success": true,
  "errors": null,
  "data": {
    "smallcases": {
      "public": [
        {
          "scid": "SCAW_0001",
          "name": "All Weather Investing",
          "investmentDetailsURL": "https://smallcase.zerodha.com/details/5f2d22636678954954f29a2d?",
          "shortDescription": "Diversify with equity, gold & fixed income ETFs for recession-proof investing",
          "imageUrl": "https://assets.smallcase.com/images/smallcases/200/SCAW_0001.png",
          "stats": {
            "currentValue": 4921.89,
            "totalReturns": -36.65253999999927
          },
          "constituents": [
            {
              "ticker": "NIFTYBEES",
              "shares": 10
            },
            {
              "ticker": "JUNIORBEES",
              "shares": 3
            },
            {
              "ticker": "LIQUIDBEES",
              "shares": 1
            },
            {
              "ticker": "GOLDBEES",
              "shares": 39
            }
          ]
        }
      ],
      "private": {
        "stats": {
          "currentValue": 57.31,
          "totalReturns": 1.3100000000000023
        }
      }
    },
    "securities": [
      {
        "holdings": {
          "quantity": 4,
          "averagePrice": 36.68
        },
        "positions": {
          "nse": {
            "quantity": 1,
            "averagePrice": 34.1
          },
          "bse": {
            "quantity": 1,
            "averagePrice": 34.1
          }
        },
        "transactableQuantity": 5,
        "smallcaseQuantity": 2,
        "nseTicker": "J&KBANK",
        "bseTicker": "J&KBANK",
        "isin": "INE168A01041",
        "name": "Jammu and Kashmir Bank Ltd"
      },
      {
        "holdings": {
          "quantity": 1,
          "averagePrice": 28.4
        },
        "positions": {
          "nse": {
            "quantity": 0,
            "averagePrice": 0
          },
          "bse": {
            "quantity": 0,
            "averagePrice": 0
          }
        },
        "transactableQuantity": 1,
        "smallcaseQuantity": 0,
        "nseTicker": "MASPTOP50",
        "bseTicker": "MASPTOP50",
        "isin": "INF769K01HP3",
        "name": "Mirae Asset S&P 500 Top 50 ETF"
      },
      {
        "holdings": {
          "quantity": 1,
          "averagePrice": 10.53
        },
        "positions": {
          "nse": {
            "quantity": 0,
            "averagePrice": 0
          },
          "bse": {
            "quantity": 0,
            "averagePrice": 0
          }
        },
        "transactableQuantity": 1,
        "smallcaseQuantity": 0,
        "nseTicker": "AXISBPSETF",
        "bseTicker": null,
        "isin": "INF846K01Z04",
        "name": "Axis AAA Bond Plus SDL ETF-2026 Matur. Reg. Growth"
      },
      {
        "holdings": {
          "quantity": 1,
          "averagePrice": 9.8
        },
        "positions": {
          "nse": {
            "quantity": 0,
            "averagePrice": 0
          },
          "bse": {
            "quantity": 0,
            "averagePrice": 0
          }
        },
        "transactableQuantity": 1,
        "smallcaseQuantity": 0,
        "nseTicker": "SUZLON",
        "bseTicker": "SUZLON",
        "isin": "INE040H01021",
        "name": "Suzlon Energy Ltd"
      },
      {
        "holdings": {
          "quantity": 1,
          "averagePrice": 48.5
        },
        "positions": {
          "nse": {
            "quantity": 0,
            "averagePrice": 0
          },
          "bse": {
            "quantity": 0,
            "averagePrice": 0
          }
        },
        "transactableQuantity": 1,
        "smallcaseQuantity": 0,
        "nseTicker": "ICICIB22",
        "bseTicker": "ICICIB22",
        "isin": "INF109KB15Y7",
        "name": "Bharat 22 ETF"
      },
      {
        "holdings": {
          "quantity": 1,
          "averagePrice": 36.05
        },
        "positions": {
          "nse": {
            "quantity": 0,
            "averagePrice": 0
          },
          "bse": {
            "quantity": 0,
            "averagePrice": 0
          }
        },
        "transactableQuantity": 1,
        "smallcaseQuantity": 0,
        "nseTicker": "PNB",
        "bseTicker": "PNB",
        "isin": "INE160A01022",
        "name": "Punjab National Bank"
      }
    ],
    "updating": false,
    "lastUpdate": "2022-03-24T11:24:00.871Z",
    "snapshotDate": "2022-03-24T11:24:00.871Z",
    "smallcaseAuthId": "6195e288360acf9ebc060d23",
    "broker": "groww"
  }
}
{
  "smallcases": {
    "public": [
      {
        "scid": "SCAW_0001",
        "name": "All Weather Investing",
        "investmentDetailsURL": "https://smallcase.zerodha.com/details/5f2d22636678954954f29a2d?",
        "shortDescription": "Diversify with equity, gold & fixed income ETFs for recession-proof investing",
        "imageUrl": "https://assets.smallcase.com/images/smallcases/200/SCAW_0001.png",
        "stats": {
          "currentValue": 4921.89,
          "totalReturns": -36.65253999999927
        },
        "constituents": [
          {
            "ticker": "NIFTYBEES",
            "shares": 10
          },
          {
            "ticker": "JUNIORBEES",
            "shares": 3
          },
          {
            "ticker": "LIQUIDBEES",
            "shares": 1
          },
          {
            "ticker": "GOLDBEES",
            "shares": 39
          }
        ]
      }
    ],
    "private": {
      "stats": {
        "currentValue": 57.31,
        "totalReturns": 1.31
      }
    }
  },
  "securities": [
    {
      "holdings": {
        "quantity": 4,
        "averagePrice": 36.68
      },
      "positions": {
        "nse": {
          "quantity": 1,
          "averagePrice": 34.1
        },
        "bse": {
          "quantity": 1,
          "averagePrice": 34.1
        }
      },
      "transactableQuantity": 5,
      "smallcaseQuantity": 2,
      "nseTicker": "J&KBANK",
      "bseTicker": "J&KBANK",
      "isin": "INE168A01041",
      "name": "Jammu and Kashmir Bank Ltd"
    },
    {
      "holdings": {
        "quantity": 1,
        "averagePrice": 28.4
      },
      "positions": {
        "nse": {
          "quantity": 0,
          "averagePrice": 0
        },
        "bse": {
          "quantity": 0,
          "averagePrice": 0
        }
      },
      "transactableQuantity": 1,
      "smallcaseQuantity": 0,
      "nseTicker": "MASPTOP50",
      "bseTicker": "MASPTOP50",
      "isin": "INF769K01HP3",
      "name": "Mirae Asset S&P 500 Top 50 ETF"
    },
    {
      "holdings": {
        "quantity": 1,
        "averagePrice": 10.53
      },
      "positions": {
        "nse": {
          "quantity": 0,
          "averagePrice": 0
        },
        "bse": {
          "quantity": 0,
          "averagePrice": 0
        }
      },
      "transactableQuantity": 1,
      "smallcaseQuantity": 0,
      "nseTicker": "AXISBPSETF",
      "bseTicker": null,
      "isin": "INF846K01Z04",
      "name": "Axis AAA Bond Plus SDL ETF-2026 Matur. Reg. Growth"
    },
    {
      "holdings": {
        "quantity": 1,
        "averagePrice": 9.8
      },
      "positions": {
        "nse": {
          "quantity": 0,
          "averagePrice": 0
        },
        "bse": {
          "quantity": 0,
          "averagePrice": 0
        }
      },
      "transactableQuantity": 1,
      "smallcaseQuantity": 0,
      "nseTicker": "SUZLON",
      "bseTicker": "SUZLON",
      "isin": "INE040H01021",
      "name": "Suzlon Energy Ltd"
    },
    {
      "holdings": {
        "quantity": 1,
        "averagePrice": 48.5
      },
      "positions": {
        "nse": {
          "quantity": 0,
          "averagePrice": 0
        },
        "bse": {
          "quantity": 0,
          "averagePrice": 0
        }
      },
      "transactableQuantity": 1,
      "smallcaseQuantity": 0,
      "nseTicker": "ICICIB22",
      "bseTicker": "ICICIB22",
      "isin": "INF109KB15Y7",
      "name": "Bharat 22 ETF"
    },
    {
      "holdings": {
        "quantity": 1,
        "averagePrice": 36.05
      },
      "positions": {
        "nse": {
          "quantity": 0,
          "averagePrice": 0
        },
        "bse": {
          "quantity": 0,
          "averagePrice": 0
        }
      },
      "transactableQuantity": 1,
      "smallcaseQuantity": 0,
      "nseTicker": "PNB",
      "bseTicker": "PNB",
      "isin": "INE160A01022",
      "name": "Punjab National Bank"
    }
  ],
  "updating": false,
  "lastUpdate": "2022-03-24T11:33:52.986Z",
  "snapshotDate": "2022-03-24T11:24:00.871Z",
  "notes": "your-notes-goes-here",
  "smallcaseAuthId": "6195e288360acf9ebc060d23",
  "broker": "groww",
  "transactionId": "TRX_06726c28769e44b8920bd6eb5bbeef17",
  "timestamp": "2022-03-24T11:33:53.091Z",
  "checksum": "fe7a17d4f82831918a1363af080f5a92f382efa872b1a2a7823964b6bf7e3285"
}

Known issues 🛠

Broker-specific known data discrepancies are listed at -
https://developers.gateway.smallcase.com/page/holdings-import-v2-known-data-discrepancy

Keep reading 🔖