> For the complete documentation index, see [llms.txt](https://synthesys-2.gitbook.io/synthesys-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://synthesys-2.gitbook.io/synthesys-docs/network-overview/integration-guide.md).

# Integration Guide

This guide covers how sub-distributors integrate with the Synthesys Network API to submit subscription and redemption orders programmatically.

**Base URL:** `https://network-staging.api.synthesys.co/api/v1`

All order endpoints require a Bearer token. Obtain one by calling `POST /api/v1/auth/token` with your API key and secret — both issued by Pinetree at onboarding.

***

### Step 1: Authenticate

**Endpoint:** `POST /api/v1/auth/token`

| Header         | Required | Description                          |
| -------------- | -------- | ------------------------------------ |
| `x-api-key`    | Yes      | Your API key provided by Pinetree    |
| `x-api-secret` | Yes      | Your API secret provided by Pinetree |

json

```json
// Response
{
  "data": {
    "accessToken": "<token>",
    "refreshToken": "<token>",
    "tokenType": "Bearer",
    "expiresIn": 900
  }
}
```

Use the `accessToken` as a `Bearer` token in the `Authorization` header for all subsequent requests. Tokens expire after 15 minutes — use `POST /api/v1/auth/refresh` with your `refreshToken` to renew.

> 💡 Your `distributorId` (format: `PT######`) and `shareClassId` (format: `SC######`) are issued by Pinetree at onboarding. Both are required on every order.

***

### Step 2: Look Up Fund Data (Optional)

| What                     | Endpoint                                                          |
| ------------------------ | ----------------------------------------------------------------- |
| List all available funds | `GET /api/v1/assets/shareclass/all`                               |
| Get a specific fund      | `GET /api/v1/assets/shareclass/:shareClassId`                     |
| Get live NAV             | `GET /api/v1/assets/shareclass/nav/live?shareClassId=SC######`    |
| Get NAV history          | `GET /api/v1/assets/shareclass/nav/history?shareClassId=SC######` |

***

### Step 3: Register Your Investors

Register each investor before placing orders on their behalf. This returns a `userId` required on every order.

**Endpoint:** `POST /api/v1/user/register`

| Field           | Type   | Required | Description                                   |
| --------------- | ------ | -------- | --------------------------------------------- |
| `email`         | string | Yes      | Investor's email address                      |
| `name`          | string | Yes      | Investor's display name                       |
| `distributorId` | string | No       | Your distributor ID (`PT######`)              |
| `uniqueId`      | string | No       | Your own internal reference for this investor |

***

### Step 4a: Place a Subscription Order

**Endpoint:** `POST /api/v1/orders/subscribe`

| Field           | Type   | Required | Description                                      |
| --------------- | ------ | -------- | ------------------------------------------------ |
| `distributorId` | string | Yes      | Your distributor ID, format `PT######`           |
| `userId`        | string | Yes      | Investor's user ID, format `US######`            |
| `shareClassId`  | string | Yes      | Fund share class ID, format `SC######`           |
| `amount`        | number | Yes      | Subscription amount in settlement currency (≥ 0) |
| `currency`      | string | No       | Currency code (e.g. `USD`, `USDC`)               |
| `walletAddress` | string | No       | Wallet to receive fund tokens                    |
| `chainId`       | string | No       | Blockchain network ID for token delivery         |

json

```json
// Example
{
  "distributorId": "PT000123",
  "userId": "US000456",
  "shareClassId": "SC000789",
  "amount": 50000,
  "currency": "USD",
  "walletAddress": "0xabc...def",
  "chainId": "1"
}
```

After submitting, transfer the fiat or stablecoin amount to Pinetree. Fund tokens will be delivered to the specified wallet within one business day of the daily cut-off.

***

### Step 4b: Place a Redemption Order

**Endpoint:** `POST /api/v1/orders/redeem`

| Field           | Type   | Required | Description                              |
| --------------- | ------ | -------- | ---------------------------------------- |
| `distributorId` | string | Yes      | Your distributor ID, format `PT######`   |
| `userId`        | string | Yes      | Investor's user ID, format `US######`    |
| `shareClassId`  | string | Yes      | Fund share class ID, format `SC######`   |
| `tokenCount`    | number | Yes      | Number of fund tokens to redeem (≥ 0)    |
| `walletAddress` | string | No       | Wallet holding the tokens to be redeemed |
| `chainId`       | string | No       | Blockchain network ID of the tokens      |

json

```json
// Example
{
  "distributorId": "PT000123",
  "userId": "US000456",
  "shareClassId": "SC000789",
  "tokenCount": 5000,
  "walletAddress": "0xabc...def",
  "chainId": "1"
}
```

After submitting, transfer the fund tokens to Pinetree. Fiat or stablecoin proceeds will be returned to you within one business day of the daily cut-off.

***

### Step 5: Track Order Status

| Action                 | Endpoint                              |
| ---------------------- | ------------------------------------- |
| Get order by ID        | `GET /api/v1/orders/:id`              |
| Cancel a pending order | `POST /api/v1/orders/cancel/:orderId` |

***

### Step 6: Set Up Webhooks (Recommended)

Register a webhook to receive real-time event notifications instead of polling.

**Endpoint:** `POST /api/v1/webhooks/register`

| Field          | Type   |
| -------------- | ------ |
| `event_type`   | string |
| `endpoint_url` | string |

**Available Events:**

| Event                      | Triggered when                                       |
| -------------------------- | ---------------------------------------------------- |
| `order.accepted`           | Pinetree accepts and begins processing the order     |
| `order.rejected`           | Order rejected (failed validation or missed cut-off) |
| `token.transfer_completed` | Fund tokens successfully delivered to wallet         |
| `token.transfer_failed`    | Token delivery failed                                |

> 💡 Subscribe to both `order.accepted` and `token.transfer_completed` to track the full lifecycle — acceptance does not guarantee delivery.

***

### Step 7: Check Holdings

**Endpoint:** `GET /api/v1/transaction/holdings/user/:userId/shareclass/:shareClassId`

Returns `tokenBalance`, wallet address, token name, symbol, and decimals.

***

### Data Points Provided at Onboarding

| Data Point       | Format                | Used in                                       |
| ---------------- | --------------------- | --------------------------------------------- |
| `distributorId`  | `PT######`            | Every order request                           |
| `shareClassId`   | `SC######`            | Every order, NAV queries, holdings            |
| `userId`         | `US######`            | Per investor — obtained via `/user/register`  |
| `walletAddress`  | Ethereum address      | Token delivery (subscription) or redemption   |
| `chainId`        | e.g. `1` for Ethereum | Specifies the blockchain network              |
| API key & secret | Provided by Pinetree  | Used to obtain Bearer token via `/auth/token` |

***

### Next Steps

* API Reference — Full endpoint documentation with request/response schemas.
* Compliance & Security — KYC, whitelisting, and token transfer controls.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://synthesys-2.gitbook.io/synthesys-docs/network-overview/integration-guide.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.