Onboarding API

The Onboarding API allows external partners to onboard users to Superstate by submitting KYC-verified user data along with the user's wallet addresses to the be added to Superstate's onchain allowlist. Once onboarded, users are eligible to hold and trade equity tokens.

Authentication

All endpoints require API key authentication with the OnboardingApi role. Contact Superstate for an API key.

Sending a Request

For information on how to send a request, please see the API key section on the API page.

Endpoints Overview

Method	Path	Description
POST	/v1/accounts/onboard/svm	Create a new entity on Solana
POST	/v1/accounts/onboard/svm/mock	Mock create on Solana (testing)
POST	/v1/accounts/onboard/svm/add-allowlist	Add allowlist address on Solana
POST	/v1/accounts/onboard/evm	Create a new entity on EVM
POST	/v1/accounts/onboard/evm/mock	Mock create on EVM (testing)
POST	/v1/accounts/onboard/evm/add-allowlist	Add allowlist address on EVM
PUT	/v1/accounts/onboard/update	Update an existing entity's data

---

Create Individual - SVM

POST /v1/accounts/onboard/svm

Creates a new entity and adds the user's Solana wallet address to the allowlist. Returns a JSON-serialized partially-signed transaction that the user must sign and broadcast to complete the allowlist addition.

Request Body

Field	Type	Required	Description
version	integer	Yes	The version of this API call (currently 1)
userData	object	No	User's KYC data. If not provided, the KYC provider will be queried. See Individual User Data and Entity User Data
cluster	string	Yes	The Solana cluster. Allowed values: MainnetBeta, Devnet
walletAddress	string	Yes	The user's Solana wallet address (base58-encoded public key)
kycProvider	string	Yes	The KYC provider used to verify the user. See KYC Providers
kycProviderId	string	Yes	The unique identifier or share token from the KYC provider's verification result
forInstrument	string	No	Reserved for private allowlist onboarding. Must be omitted or null

Example Request

{
  "version": 1,
  "userData": {
    "firstName": "John",
    "middleName": "Michael",
    "lastName": "Doe",
    "ssnOrTin": "123-45-6789",
    "emailAddress": "[email protected]",
    "streetAddress": "123 Main Street",
    "city": "New York",
    "state": "NY",
    "zipcode": "10010",
    "country": "US"
  },
  "cluster": "Devnet",
  "walletAddress": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
  "kycProvider": "Sumsub",
  "kycProviderId": "01234567890123456789"
}

Response

Success (200)

{
  "entityId": 598,
  "walletAddress": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
  "encodedTransaction": "<JSON-serialized partially-signed Solana transaction>"
}

Field	Type	Description
entityId	integer	The newly created (or existing) entity ID
walletAddress	string	The wallet address that was added to the allowlist
encodedTransaction	string	JSON-serialized Solana transaction. The user must sign and broadcast this to complete the allowlist addition

Validation Rules

• Wallet address must be a valid Solana public key (base58)

• Wallet address must not already be on the allowlist for the selected cluster

• Wallet address must not be a program/contract address

• If the email address already exists in Superstate's system, the existing entity will be reused

---

Create Individual - EVM

POST /v1/accounts/onboard/evm

Creates a new entity and adds the user's EVM wallet address to the allowlist. Returns JSON-serialized EIP-712 signature parameters for the setUserPermissionForInstrument contract function.

Request Body

Field	Type	Required	Description
version	integer	Yes	The version of this API call (currently 1)
userData	object	No	User's KYC data. If not provided, the KYC provider will be queried. See Individual User Data and Entity User Data
chainId	integer	Yes	The EVM chain ID. See Supported Chain IDs
walletAddress	string	Yes	The user's EVM wallet address (0x-prefixed hex)
kycProvider	string	Yes	The KYC provider used to verify the user. See KYC Providers
kycProviderId	string	Yes	The unique identifier or share token from the KYC provider's verification result
forInstrument	string	No	Reserved for private allowlist onboarding. Must be omitted or null

Example Request

{
  "version": 1,
  "userData": {
    "firstName": "Jane",
    "lastName": "Smith",
    "ssnOrTin": "987-65-4321",
    "emailAddress": "[email protected]",
    "streetAddress": "456 Oak Avenue",
    "city": "Los Angeles",
    "state": "CA",
    "zipcode": "90210",
    "country": "US"
  },
  "chainId": 1,
  "walletAddress": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
  "kycProvider": "Sumsub",
  "kycProviderId": "98765432109876543210"
}

Response

Success (200)

{
  "entityId": 598,
  "walletAddress": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
  "encodedTransaction": "<JSON-serialized EIP-712 signature parameters for setUserPermissionForInstrument>"
}

Field	Type	Description
entityId	integer	The newly created (or existing) entity ID
walletAddress	string	The wallet address that was added to the allowlist
encodedTransaction	string	JSON-serialized EIP-712 signature parameters. Use these to call setUserPermissionForInstrument on the allowlist contract

Validation Rules

Same as SVM, but for EVM addresses:

• Wallet address must be a valid EVM address (0x-prefixed, 40 hex characters)

• Wallet address must not already be on the allowlist for the specified chain

• Wallet address must not be a smart contract address

• Chain ID must be a supported EVM chain

---

Mock Endpoints

POST /v1/accounts/onboard/svm/mock

POST /v1/accounts/onboard/evm/mock

Mock endpoints for testing your integration. They accept the same request bodies as their non-mock counterparts but:

• Skip all database operations — no entities, users, or organizations are created

• Skip input validation — wallet address and chain checks are bypassed

• Return mock data — entityId is always 0

SVM mock: Returns a JSON-serialized Solana transaction with an invalid blockhash (all zeros) and unsigned signatures. This transaction cannot be broadcast.

EVM mock: Returns JSON-serialized setUserPermissionForInstrument parameters with deadline set to 0 (expired) and zero-value signatures. This cannot be used on-chain.

Example Response (SVM Mock)

{
  "entityId": 0,
  "walletAddress": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
  "encodedTransaction": "<JSON-serialized mock Solana transaction>"
}

Example Response (EVM Mock)

{
  "entityId": 0,
  "walletAddress": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
  "encodedTransaction": "<JSON-serialized mock EIP-712 parameters with expired deadline>"
}

---

Add Allowlist Address - SVM

POST /v1/accounts/onboard/svm/add-allowlist

Adds a new Solana wallet address to the allowlist for an existing user. The user is identified by either their email address or an existing allowlisted wallet address.

Request Body

Field	Type	Required	Description
version	integer	Yes	The version of this API call (currently 1)
email	string	Conditional	Email of the user. Mutually exclusive with existingWalletAddress — exactly one must be provided
existingWalletAddress	string	Conditional	An existing allowlisted wallet address to identify the user. Mutually exclusive with email
walletAddress	string	Yes	The new wallet address to add to the allowlist
forInstrument	string	No	Reserved for private allowlist onboarding. Must be omitted or null

Note: The SVM chain is determined automatically from the server's configured environment. There is no cluster field on this endpoint.

Example Request (using email)

{
  "version": 1,
  "email": "[email protected]",
  "walletAddress": "BKgGvQR3TmEy8zNBJfwDEVGZmt7dRUXVZDiPKYCFaLWd"
}

Example Request (using existing wallet address)

{
  "version": 1,
  "existingWalletAddress": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
  "walletAddress": "BKgGvQR3TmEy8zNBJfwDEVGZmt7dRUXVZDiPKYCFaLWd"
}

Response

Success (200)

{
  "entityId": 598,
  "walletAddress": "BKgGvQR3TmEy8zNBJfwDEVGZmt7dRUXVZDiPKYCFaLWd",
  "encodedTransaction": "<JSON-serialized partially-signed Solana transaction>"
}

Authorization

The requesting partner must be the same partner that originally onboarded the entity. If a different partner attempts to add an allowlist address, the request will be rejected with 403 Forbidden.

---

Add Allowlist Address - EVM

POST /v1/accounts/onboard/evm/add-allowlist

Adds a new EVM wallet address to the allowlist for an existing user. The user is identified by either their email address or an existing allowlisted wallet address.

Request Body

Field	Type	Required	Description
version	integer	Yes	The version of this API call (currently 1)
email	string	Conditional	Email of the user. Mutually exclusive with existingWalletAddress — exactly one must be provided
existingWalletAddress	string	Conditional	An existing allowlisted wallet address to identify the user. Mutually exclusive with email
chainId	integer	Yes	The EVM chain ID for the new address. See Supported Chain IDs
walletAddress	string	Yes	The new EVM wallet address to add to the allowlist
forInstrument	string	No	Reserved for private allowlist onboarding. Must be omitted or null

Example Request

{
  "version": 1,
  "email": "[email protected]",
  "chainId": 1,
  "walletAddress": "0x1234567890abcdef1234567890abcdef12345678"
}

Response

Success (200)

{
  "entityId": 598,
  "walletAddress": "0x1234567890abcdef1234567890abcdef12345678",
  "encodedTransaction": "<JSON-serialized EIP-712 signature parameters>"
}

Authorization

Same as SVM — the requesting partner must be the same partner that originally onboarded the entity.

---

Update Entity

PUT /v1/accounts/onboard/update

Updates an existing entity's onboarding data. Only the fields provided in the request will be updated — all other fields remain unchanged (partial update). The request body must include a type field to indicate whether this is an individual or entity update. An individual cannot be converted to an entity and vice versa. Only the company who onboarded the user initially can update the user's data.

Request Body

Field	Type	Required	Description
entityId	integer	Yes	The entity ID to update
userData	object	Yes	The fields to update. Must include type set to "individual" or "entity"

Individual Update Fields

All fields are optional. Only provided fields will be updated.

Field	Type	Description
type	string	Must be "individual"
firstName	string	First name (1-100 characters)
middleName	string	Middle name (1-100 characters)
lastName	string	Last name (1-100 characters)
ssnOrTin	string	SSN or Tax ID (digits and hyphens only, 1-20 characters)
emailAddress	string	Valid email address
streetAddress	string	Street address (1-100 characters)
city	string	City (1-40 characters)
state	string	State or province abbreviation (1-3 characters)
zipcode	string	ZIP or postal code (1-11 characters)
country	string	ISO 3166-1 alpha-2 country code (exactly 2 characters)

Entity Update Fields

All fields are optional. Only provided fields will be updated.

Field	Type	Description
type	string	Must be "entity"
entityName	string	Entity name (1-100 characters)
entityType	string	Investor type (e.g., "Corporation", "LLC", "Partnership", "Trust")
ssnOrTin	string	Tax ID (digits and hyphens only, 1-20 characters)
emailAddress	string	Valid email address
streetAddress	string	Street address (1-100 characters)
city	string	City (1-40 characters)
state	string	State or province abbreviation (1-3 characters)
zipcode	string	ZIP or postal code (1-11 characters)
country	string	ISO 3166-1 alpha-2 country code (exactly 2 characters)

Example Request (Individual)

{
  "entityId": 598,
  "userData": {
    "type": "individual",
    "firstName": "Jonathan",
    "streetAddress": "789 New Street"
  }
}

Example Request (Entity)

{
  "entityId": 599,
  "userData": {
    "type": "entity",
    "entityName": "Updated Corp LLC"
  }
}

Response

Success (200)

Returns an empty response body on success.

Authorization

The requesting partner must be the same partner that originally onboarded the entity. If a different partner attempts to update the entity, the request will be rejected with 403 Forbidden.

---

Reference

Individual User Data

Used in the userData field of create endpoints when onboarding an individual.

Field	Type	Required	Validation
firstName	string	Yes	1-100 characters
middleName	string	No	1-100 characters
lastName	string	Yes	1-100 characters
ssnOrTin	string	Yes	Digits and hyphens only (^[0-9-]+$), 1-20 characters
emailAddress	string	Yes	Valid email address
streetAddress	string	Yes	1-100 characters
city	string	Yes	1-40 characters
state	string	No	1-3 characters (state/province abbreviation)
zipcode	string	Yes	1-11 characters
country	string	Yes	Exactly 2 characters (ISO 3166-1 alpha-2 country code)

Entity User Data

Used in the userData field of create endpoints when onboarding a non-individual entity (corporation, LLC, etc.).

Field	Type	Required	Validation
entityName	string	Yes	1-100 characters
entityType	string	Yes	Investor type (e.g., "Corporation", "LLC", "Partnership", "Trust")
ssnOrTin	string	Yes	Digits and hyphens only (^[0-9-]+$), 1-20 characters
emailAddress	string	Yes	Valid email address
streetAddress	string	Yes	1-100 characters
city	string	Yes	1-40 characters
state	string	No	1-3 characters (state/province abbreviation)
zipcode	string	Yes	1-11 characters
country	string	Yes	Exactly 2 characters (ISO 3166-1 alpha-2 country code)

Note: The userData field on create endpoints uses untagged deserialization. The API will attempt to parse as an individual first, then as an entity. Ensure your payload matches one of the two schemas above.

Supported EVM Chain IDs

Chain ID	Network
1	Ethereum Mainnet
11155111	Ethereum Sepolia Testnet
98866	Plume Mainnet
98867	Plume Testnet

For SVM, use the cluster field with values MainnetBeta or Devnet instead of a chain ID.

Error Responses

Status Code	Description
400	Bad request — invalid input, validation failure, wallet already on allowlist, or API key not enabled
401	Unauthorized — invalid or missing API key
403	Forbidden — partner did not onboard this entity (for update and add-allowlist endpoints)
500	Internal server error