Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Onboarding API

The Onboarding API allows external partners to onboard users to Superstate by submitting KYC-verified user data along with wallet addresses to the be added to Superstate's on-chain allowlist

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

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 bincode + base64 encoded 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

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

Response

Success (200)

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

Encoded (bincode, then base64-string), partially-signed Solana transaction. The user must sign and broadcast this to complete the allowlist addition

to

null

Will be null for SVM since the target is encoded in the encodedTransaction already

Validation Rules

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

  • Wallet address must not already be on the allowlist for the environment (production, staging, etc)

  • 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 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

Response

Success (200)

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

ABI-encoded function data that can be used directly in the transaction data field

to

string

Address of the Superstate Allowlist proxy 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 bincode + base64 encoded Solana transaction with an invalid blockhash (all zeros) and unsigned signatures. This transaction cannot be broadcast.

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

Example Response (SVM Mock)

Example Response (EVM Mock)

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

entityId

integer

Conditional

An existing entityId of a previously API-onboarded entity.

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.

Example Request (using email)

Example Request (using existing wallet address)

Example Request (using entity ID)

Response

Success (200)

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

entityId

integer

Conditional

An existing entityId of a previously API-onboarded entity.

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 (using email)

Example Request (using existing wallet address)

Example Request (using entity ID)

Response

Success (200)

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)

Example Request (Entity)

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 (US only)

Digits and hyphens only (^[0-9-]+$), 1-20 characters. Required for US only.

emailAddress

string

Yes

Valid email address

streetAddress

string

Yes

1-100 characters

city

string

Yes

1-40 characters

state

string

No

1-40 characters (state abbreviation for US, freeform for ex-US)

zipcode

string

No

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

Available values: Individual, Corporation, LimitedPartnership, GeneralPartnership, SCorp, Trust, Llc, Llp, Other

ssnOrTin

string

Yes (US only)

Digits and hyphens only (^[0-9-]+$), 1-20 characters. Required for US only.

businessRegistrationNumber

string

Yes (ex-US only)

Digits and hyphens only (^[0-9-]+$), 1-20 characters. Required for ex-US only.

emailAddress

string

Yes

Valid email address

streetAddress

string

Yes

1-100 characters

city

string

Yes

1-40 characters

state

string

No

1-40 characters (state abbreviation for US, freeform for ex-US)

zipcode

string

No

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, we will automatically use MainnetBeta or Devnet based on the environment on which the API was sent.

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

PreviousOpening Bell
NextDirect Issuance Program

Last updated