add all the routes and some examples

transfer-agent-protocol · May 27, 2024 · 76128c4 · 76128c4
1 parent a86edc0
commit 76128c4
Show file tree

Hide file tree

Showing 12 changed files with 513 additions and 3 deletions.
diff --git a/src/pages/features.mdx b/src/pages/features.mdx
@@ -1,5 +1,21 @@
-import { Cards, Card, Callout } from 'nextra/components';
+import { Card, Cards, Callout, FileTree } from 'nextra/components'
 
 # Protocol Features
 
-<Callout emoji="⏳">Docs are in public preview; section coming soon</Callout>
+<Callout emoji="⏳" type="info">Docs are in public preview and are being  updated</Callout>
+
+## API Routes
+
+All the available API routes, and their purpose, method, and parameters that you can use.
+
+<Cards>
+  <Card title="Issuer" href="/features/issuer" />
+  <Card title="Stock Class" href="/features/stock-class" />
+  <Card title="Stock Legend Templates" href="/features/stock-legend" />
+  <Card title="Stock Plan" href="/features/stock-plan" />
+  <Card title="Valuation" href="/features/valuation" />
+  <Card title="Vesting Terms" href="/features/vesting-terms" />
+  <Card title="Stakeholder" href="/features/stakeholder" />
+  <Card title="Transaction" href="/features/transactions" />
+  <Card title="Historical Transactions" href="/features/historical-transactions" />
+</Cards>
diff --git a/src/pages/features/_meta.json b/src/pages/features/_meta.json
@@ -0,0 +1,9 @@
+{
+    "issuer": "Issuer",
+    "stock-class": "Stock Class",
+    "stock-legend": "Stock Legend",
+    "valuation": "Valuation",
+    "vesting-terms": "Vesting Terms",
+    "stakeholder": "Stakeholder",
+    "historical-transactions": "Historical Transactions"
+}
diff --git a/src/pages/features/historical-transactions.mdx b/src/pages/features/historical-transactions.mdx
@@ -0,0 +1,8 @@
+# Historical Transactions Routes
+
+## `historical-transactions/issuer-id/:id`
+
+- **Description**: Retrieves historical transactions for an issuer by ID.
+- **Method**: `GET`
+- **Parameters** (URL):
+  - `id`: The ID of the issuer (string).
diff --git a/src/pages/features/issuer.mdx b/src/pages/features/issuer.mdx
@@ -0,0 +1,54 @@
+# Issuer Routes
+
+This is the very first thing to be created - issuer with the `issuerId`. To create one, you post this data to the specified route. Our server will generate an `issuerId` automatically and create a database replica of the onchain record.
+
+## `issuer/create`
+
+- **Description**: Creates a new issuer.
+- **Method**: `POST`
+- **Parameters** (body):
+  - `legal_name`: The name of the issuer (string).
+  - `formation_date`: The date of formation (string, format: YYYY-MM-DD).
+  - `country_of_formation`: The country of formation (string).
+  - `country_subdivision_of_formation`: The country subdivision of formation (string).
+  - `initial_shares_authorized`: The number of initial shares authorized (string).
+  - `tax_ids`: List of tax IDs (array of objects with `tax_id` and `country`).
+  - `email`: The email address (object with `email_address` and `email_type`).
+  - `address`: The legal address (object with `address_type`, `street_suite`, `city`, `country_subdivision`, `country`, and `postal_code`).
+  - `comments`: Additional comments (array of strings).
+
+````json
+{
+    "legal_name": "Transfer Agent Protocol",
+    "formation_date": "2024-01-12",
+    "country_of_formation": "US",
+    "country_subdivision_of_formation": "DE",
+    "initial_shares_authorized": "10000000",
+    "tax_ids": [
+        {
+            "tax_id": "88-3977591",
+            "country": "US"
+        }
+    ],
+    "email": {
+        "email_address": "[email protected]",
+        "email_type": "BUSINESS"
+    },
+    "address": {
+        "address_type": "LEGAL",
+        "street_suite": "447 Broadway\n2nd Fl #713",
+        "city": "New York",
+        "country_subdivision": "NY",
+        "country": "US",
+        "postal_code": "10013"
+    },
+    "comments": []
+}
+````
+
+## `issuer/id/:id`
+
+- **Description**: Retrieves details of an issuer by ID. For example, if the server generated this as the `issuerId` `92dddedd-251d-47cd-83ac-342f00e3d5a1`, we'll have to use it throughout to modify records for this specific issuer.
+- **Method**: `GET`
+- **Parameters** (URL):
+  - `id`: The ID of the issuer (string).
diff --git a/src/pages/features/stakeholder.mdx b/src/pages/features/stakeholder.mdx
@@ -0,0 +1,114 @@
+# Stakeholder Routes
+
+One of the most interesting and important routes - given the `issuerId`, stakeholders can be added to the cap table.
+
+## `stakeholder/create`
+
+- **Description**: Creates a new stakeholder.
+- **Method**: `POST`
+- **Parameters** (body):
+  - `issuerId`: The ID of the issuer (string).
+  - `data`: The stakeholder data (object with the following fields):
+    - `name`: The name of the stakeholder (object with `legal_name`, `first_name`, and `last_name`).
+    - `issuer_assigned_id`: The ID assigned by the issuer (string).
+    - `stakeholder_type`: The type of stakeholder (string, e.g., "INDIVIDUAL").
+    - `current_relationship`: The current relationship (string).
+    - `primary_contact`: The primary contact information (object with `name`, `emails`, and `phone_numbers`).
+    - `contact_info`: Additional contact information (object with `emails` and `phone_numbers`).
+    - `comments`: Additional comments (array of strings).
+
+````json
+{
+  "issuerId": "92dddedd-251d-47cd-83ac-342f00e3d5a1",
+  "data": {
+    "name": {
+      "legal_name": "Alex Palmer",
+      "first_name": "Alex",
+      "last_name": "Palmer"
+    },
+    "issuer_assigned_id": "",
+    "stakeholder_type": "INDIVIDUAL",
+    "current_relationship": "FOUNDER",
+    "primary_contact": {
+      "name": {
+        "legal_name": "Alex Palmer",
+        "first_name": "Alex",
+        "last_name": "Palmer"
+      },
+      "emails": [
+        {
+          "email_type": "PERSONAL",
+          "email_address": "[email protected]" // this is real, you can ping me with questions
+        }
+      ],
+      "phone_numbers": [
+        {
+          "phone_type": "MOBILE",
+          "phone_number": "+1 212 420 6994" // this is fake guys
+        }
+      ]
+    },
+    "contact_info": {
+      "emails": [
+        {
+          "email_type": "PERSONAL",
+          "email_address": "[email protected]"
+        }
+      ],
+      "phone_numbers": [
+        {
+          "phone_type": "MOBILE",
+          "phone_number": "+1 212 420 6994"
+        }
+      ]
+    },
+    "comments": []
+  }
+}
+````
+
+## `stakeholder/add-wallet`
+
+This is used to add a wallet that the stakeholder is using to custody shares on the cap table, by issuer
+
+- **Description**: Adds a wallet to a stakeholder.
+- **Method**: `POST`
+- **Parameters** (body):
+  - `issuerId`: The ID of the issuer (string).
+  - `wallet`: The wallet address to add (string).
+
+````json
+{
+	"issuerId": "92dddedd-251d-47cd-83ac-342f00e3d5a1",
+    "wallet": "0x3601a913fD3466f30f5ABb978E484d1B37Ce995D"
+}
+````
+
+## `stakeholder/remove-wallet`
+
+Something bad happened to the wallet? Does the stakeholder want to use another one and remove the current one? This is how we do it.
+
+- **Description**: Removes a wallet from a stakeholder.
+- **Method**: `POST`
+- **Parameters** (body):
+  - `id`: The ID of the stakeholder (string).
+  - `wallet`: The wallet address to remove (string).
+
+````json
+{
+	"issuerId": "92dddedd-251d-47cd-83ac-342f00e3d5a1",
+    "wallet": "0x3601a913fD3466f30f5ABb978E484d1B37Ce995D"
+}
+````
+
+## `stakeholder/onchain/id/:id`
+
+- **Description**: Retrieves onchain details of a stakeholder by ID.
+- **Method**: `GET`
+- **Parameters** (URL):
+  - `id`: The ID of the stakeholder (string).
+
+## `stakeholder/total-number`
+
+- **Description**: Retrieves the total number of stakeholders.
+- **Method**: `GET`
diff --git a/src/pages/features/stock-class.mdx b/src/pages/features/stock-class.mdx
@@ -0,0 +1,56 @@
+# Stock Class Routes
+
+The second thing to be created after the [issuer](/features/issuer) (every issuer must have a stock class, with its corresponding id). To create an stock class, we have to know the `issuerId` (just like in the example below). Stock class will now have its own id.
+
+## `stock-class/create`
+
+- **Description**: Creates a new stock class.
+- **Method**: `POST`
+- **Parameters** (body):
+  - `issuerId`: The ID of the issuer (string).
+  - `data`: The stock class data (object with the following fields):
+    - `name`: The name of the stock class (string).
+    - `class_type`: The type of stock class (string, e.g., "COMMON").
+    - `default_id_prefix`: The default ID prefix (string).
+    - `initial_shares_authorized`: The number of initial shares authorized (string).
+    - `votes_per_share`: The number of votes per share (string).
+    - `price_per_share`: The price per share (object with `currency` and `amount`).
+    - `seniority`: The seniority of the stock class (string).
+    - `comments`: Additional comments (array of strings).
+
+````json
+{
+    "issuerId": "92dddedd-251d-47cd-83ac-342f00e3d5a1",
+    "data": {
+        "name": "Series A Common",
+        "class_type": "COMMON",
+        "default_id_prefix": "CS-A",
+        "initial_shares_authorized": "1000000",
+        // "board_approval_date": "", // IF NO DATE, then omit
+        "votes_per_share": "1",
+        // "par_value": {}, // same as date
+        "price_per_share": {
+            "currency": "USD",
+            "amount": "4.20"
+        },
+        "seniority": "1",
+        // "conversion_rights": {}, // same as date
+        // "liquidation_preference_multiple": "", // same as date
+        // "participation_cap_multiple": "", // same as date
+        "comments": []
+    }
+}
+````
+
+## `stock-class/id/:id`
+
+- **Description**: Retrieves details of a stock class by ID.
+- **Method**: `GET`
+- **Parameters** (URL):
+  - `id`: The ID of the stock class (string).
+
+## `stock-class/total-number`
+
+- **Description**: Retrieves the total number of stock classes.
+- **Method**: `GET`
+
diff --git a/src/pages/features/stock-legend.mdx b/src/pages/features/stock-legend.mdx
@@ -0,0 +1,40 @@
+# Stock Legend Templates Routes
+
+Stock legend template is a re-usable template for legal and regulatory review.
+
+## `stock-legend/create`
+
+- **Description**: Creates a new stock legend template.
+- **Method**: `POST`
+- **Parameters** (body):
+  - `issuerId`: The ID of the issuer (string).
+  - `data`: The stock legend template data (object with the following fields):
+    - `name`: The name of the legend (string).
+    - `text`: The text of the legend (string).
+    - `comments`: Additional comments (array of strings).
+
+````json
+{
+    "issuerId": "92dddedd-251d-47cd-83ac-342f00e3d5a1",
+    "data": {
+        "name": "Restricted Stock Legend",
+        "text": "The shares represented by this certificate are subject to certain restrictions on transfer and may be subject to forfeiture under the terms of an agreement entered into between the registered owner and Winston Inc. Any attempted transfer of these shares in violation of the agreement is void and of no effect.",
+        "comments": [
+            "This legend is applied to restricted stock issued to early employees."
+        ]
+    }
+}
+````
+
+## `stock-legend/id/:id`
+
+- **Description**: Retrieves details of a stock legend template by ID.
+- **Method**: `GET`
+- **Parameters** (URL):
+  - `id`: The ID of the stock legend template (string).
+
+## `stock-legend/total-number`
+
+- **Description**: Retrieves the total number of stock legend templates.
+- **Method**: `GET`
+
diff --git a/src/pages/features/stock-plan.mdx b/src/pages/features/stock-plan.mdx
@@ -0,0 +1,47 @@
+# Stock Plan Routes
+
+Stock option plan is used to create and track stock plans for any given `issuedId`.
+
+## `stock-plan/create`
+
+- **Description**: Creates a new stock plan.
+- **Method**: `POST`
+- **Parameters** (body):
+  - `issuerId`: The ID of the issuer (string).
+  - `data`: The stock plan data (object with the following fields):
+    - `plan_name`: The name of the stock plan (string).
+    - `board_approval_date`: The board approval date (string, format: YYYY-MM-DD).
+    - `stockholder_approval_date`: The stockholder approval date (string, format: YYYY-MM-DD).
+    - `initial_shares_reserved`: The number of initial shares reserved (string).
+    - `default_cancellation_behavior`: The default cancellation behavior (string).
+    - `stock_class_id`: The ID of the stock class (string).
+    - `comments`: Additional comments (array of strings).
+
+````json
+{
+    "issuerId": "92dddedd-251d-47cd-83ac-342f00e3d5a1",
+    "data": {
+        "plan_name": "Transfer Agent Protocol Employee Stock Option Plan",
+        "board_approval_date": "2023-08-15",
+        "stockholder_approval_date": "2023-08-20",
+        "initial_shares_reserved": "1000000",
+        "default_cancellation_behavior": "RETURN_TO_POOL",
+        "stock_class_id": "stock-class-12345", // important
+        "comments": [
+            "This stock plan is designed for TAP employees and provides options that can be converted to company stock."
+        ]
+    }
+}
+````
+
+## `stock-plan/id/:id`
+
+- **Description**: Retrieves details of a stock plan by ID.
+- **Method**: `GET`
+- **Parameters** (URL):
+  - `id`: The ID of the stock plan (string).
+
+## `stock-plan/total-number`
+
+- **Description**: Retrieves the total number of stock plans.
+- **Method**: `GET`