> For the complete documentation index, see [llms.txt](https://docs.superstate.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.superstate.com/investors/api/getting-started-issuer-api-guide.md).

# Getting Started: Issuer API Guide

This guide is for fund issuers who want to read or manage their fund through the Superstate API. It lists which endpoints to use for each task. For request and response details, use the [Swagger reference](https://api.superstate.com/swagger-ui/).

This guide covers funds only. It does not cover equities or investor functions.

### Create an API key

Only admins of your fund can create API keys. See the [tutorial here](https://docs.superstate.com/investors/api/api-keys.md) to create your first API key.

To learn how to sign requests, see the instructions [here](https://docs.superstate.com/investors/api.md#using-api-key-authenticated-endpoints).

### Read your fund's activity

Use a View instrument or Manage instrument key. Both endpoints take your fund's integer ID. To find the ID, see [Fund Data](#fund-data).

| Use case                                                                        | Endpoint                                                                                                                              |
| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| See subscriptions, redemptions, and transfers for your fund                     | [GET /v3/instruments/{instrument\_id}/transactions](https://api.superstate.com/swagger-ui/#/Transactions/get_instrument_transactions) |
| See who holds your fund, and how many shares each holder has at a point in time | [GET /v3/instruments/{instrument\_id}/shareholders](https://api.superstate.com/swagger-ui/#/Shareholders/get_instrument_shareholders) |

### Manage your fund

For most funds, Superstate runs investor onboarding, subscriptions, and redemptions, and you do not need these endpoints. Use them only if you onboard investors and take orders yourself and record them with Superstate.

Use a Manage instrument key. These endpoints are in beta.

| Use case                                        | Endpoint                                                                                                                        |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| Add a shareholder and onboard them to your fund | [POST /v3/shareholders](https://api.superstate.com/swagger-ui/#/Shareholders%20\(v3\)/create_shareholder_v3)                    |
| Record a batch of subscriptions (up to 500)     | [POST /v3/funds/{instrument\_id}/subscriptions](https://api.superstate.com/swagger-ui/#/Issuance%20\(v3\)/submit_subscriptions) |
| Record a batch of redemptions (up to 500)       | [POST /v3/funds/{instrument\_id}/redemptions](https://api.superstate.com/swagger-ui/#/Issuance%20\(v3\)/submit_redemptions)     |
| Check the result of each row in a batch         | [GET /v3/issuance/batches/{batch\_id}](https://api.superstate.com/swagger-ui/#/Issuance%20\(v3\)/get_issuance_batch)            |

Things to know:

* Requests are safe to retry. Creating a shareholder needs an Idempotency-Key header, and each subscription or redemption row needs an idempotency\_key. If a request fails or you do not get a response, send the same request again. Superstate does not record it twice.
* Subscriptions and redemptions run asynchronously. A 201 response means Superstate accepted the batch. Each row executes when the NAV for its date is available. Check the batch for the result of each row.

### Fund data

These endpoints return fund metadata and market data. They do not need an API key. The NAV, yield, and holdings endpoints are described in [Public endpoints](https://docs.superstate.com/investors/api.md#key-examples).

| Use case                                                            | Endpoint                                                                                                                          |
| ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| Get fund metadata, including the fund's integer ID, from its ticker | [GET /v3/instruments/{instrument\_symbol}](https://api.superstate.com/swagger-ui/#/Instruments%20\(v3\)/get_instrument)           |
| Get the daily NAV per share for a date range                        | [GET /v1/funds/{id}/nav-daily](https://api.superstate.com/swagger-ui/#/funds_runtime_data_handler/net_asset_value_handler)        |
| Get the fund's daily yield for a date range                         | [GET /v2/funds/{id}/yield](https://api.superstate.com/swagger-ui/#/Funds%20Runtime%20Data%20Public%20Handler/daily_yield_handler) |
| Get the fund's current holdings                                     | [GET /v2/funds/{id}/holdings](https://api.superstate.com/swagger-ui/#/Funds%20Gateway%20Public%20Handler/get_fund_holdings)       |

<br>
