@echoxyz/sonar-core

This reference is not fully comprehensive yet, but includes docs on the more nuanced parts of the API like how to interpret the fields in EntityDetails.

`SonarClient` functions

All functions can throw an APIError.

`readEntity`

Reads an entity’s details by entity ID. This function is expected to throw a APIError with status 404 if the entity is not found. Arguments

Name	Type	Description
`saleUUID`	`string`	The UUID of the sale to get entity details for.
`entitID`	`string` \| `undefined`	The entity ID of the entity to get details for.
`walletAddress`	`string` \| `undefined`	The wallet address of the entity to get details for. Only used for a wallet linking feature, enabled for niche use-cases on request.

Returns ReadEntityResponse

Field	Type	Description
`Entity`	`EntityDetails`	The entity details.

`listAvailableEntities`

Lists all available entities for the authenticated user. Arguments

Name	Type	Description
`saleUUID`	`string`	The UUID of the sale to list entities for.

Returns ListAvailableEntitiesResponse

Field	Type	Description
`Entities`	`EntityDetails`[]	The list of entities.

`myProfile`

Fetches the authenticated user’s profile information. Arguments None. Returns MyProfileResponse

Field	Type	Description
`EntityID`	`string`	The entity ID of the authenticated user.
`EmailAddress`	`string` \| `undefined`	The email address of the authenticated user, if available.

`readEntityInvestmentHistory`

Fetches the authenticated user’s investment history, showing all Echo private group investments they have participated in. Arguments None. Returns EntityInvestmentHistoryResponse

Field	Type	Description
`Investments`	`EntityInvestment`[]	Array of investments made by the user.

EntityInvestment

Field	Type	Description
`CompanyName`	`string`	The name of the company invested in.
`Round`	`string`	The funding round name (e.g., “Series A”, “Seed”).
`InvestedOn`	`string`	ISO 8601 timestamp of when the investment was made.

Example

const investmentHistory = await client.readEntityInvestmentHistory();

console.log(`Found ${investmentHistory.Investments.length} investments`);

investmentHistory.Investments.forEach((investment) => {
  console.log(`${investment.CompanyName} - ${investment.Round}`);
  console.log(`Invested on: ${new Date(investment.InvestedOn).toLocaleDateString()}`);
});

`fetchLimits`

Fetches the commitment limits for a wallet in a sale. Use this to display the minimum and maximum commitment amounts to users. Arguments

Name	Type	Description
`saleUUID`	`string`	The UUID of the sale to fetch limits for.
`walletAddress`	`string`	The wallet address to fetch limits for.

Returns LimitsResponse

Field	Type	Description
`HasCustomCommitmentAmountLimit`	`boolean`	Whether the entity has custom commitment limits (as opposed to default sale-wide limits).
`MinCommitmentAmount`	`string`	The minimum commitment amount, expressed in payment token units.
`MaxCommitmentAmount`	`string`	The maximum commitment amount, expressed in payment token units.

`prePurchaseCheck`

Should be called at the start of the purchase flow to check whether there are any preconditions to purchase. Arguments

Name	Type	Description
`saleUUID`	`string`	The UUID of the sale to run the pre-purchase check for.
`entityID`	`string`	The ID of the entity to run the pre-purchase check for.
`walletAddress`	`string`	The wallet address of the entity to run the pre-purchase check for.

Returns PrePurchaseCheckResponse

Field	Type	Description
`ReadyToPurchase`	`boolean`	Whether the entity is ready to purchase.
`FailureReason`	`PrePurchaseFailureReason`	Populated if the entity is not ready to purchase.
`LivenessCheckURL`	`string`	URL to link the user to so that they can complete a liveness check on the Sonar site. Populated if the FailureReason is `requires-liveness`.

`readCommitmentData`

Fetches commitment data for a sale. This is a public API endpoint that does not require authentication. Arguments

Name	Type	Description
`saleUUID`	`string`	The UUID of the sale to fetch commitment data for.

Returns ReadCommitmentDataResponse

Field	Type	Description
`TotalCommitmentAmount`	`string`	The total commitment amount in the smallest payment token units as a number string.
`ClearingPriceNumerator`	`string` \| `undefined`	For auctions only: the numerator of the clearing price as a number string.
`ClearingPriceDenominator`	`string` \| `undefined`	For auctions only: the denominator of the clearing price as a number string.
`ClearingPriceMicroUSD`	`string` \| `undefined`	For auctions only: the clearing price expressed in micro-USD (1 USD = 1,000,000 micro-USD) as a number string.
`PaymentTokenDecimals`	`number`	The decimals of the payment token used in the sale.
`OfferedTokenDecimals`	`number` \| `undefined`	The decimals of the token being offered, if configured.
`UniqueCommitmentCount`	`number`	The number of unique commitments made to the sale.
`Commitments`	`Commitment[]`	Array of individual commitments, sorted by creation time descending.

For auctions, the clearing price is expressed in terms of a ClearingPriceNumerator and ClearingPriceDenominator fraction. The clearing price is in smallest units of the payment token per smallest unit of the offered token. You can divide the ClearingPriceNumerator by the ClearingPriceDenominator to get the price in decimal format, but you might lose precision. The ClearingPriceMicroUSD field is provided for convenience to avoid the need to divide the numerator and denominator. It is only set if the sale is using an auction pricing strategy and the payment token is a USD stablecoin and the offered token decimals are configured. It contains the current clearing price in micro-USD for one human-readable offered token (1 human-readable token = 10^OfferedTokenDecimals smallest units). Warning: this could lose precision, so ClearingPriceNumerator and ClearingPriceDenominator should be used as the machine-readable value.

`generatePurchasePermit`

For onchain sales, generatePurchasePermit should be called as part of the purchase flow to generate a purchase permit to pass to the sale contract. The permit is signed by Sonar, and the contract will need to verify the signature as well as the permit data. Arguments

Name	Type	Description
`saleUUID`	`string`	The UUID of the sale to generate the purchase permit for.
`entityID`	`string`	The ID of the entity to generate the purchase permit for.
`walletAddress`	`string`	The wallet address of the entity to generate the purchase permit for.

Returns GeneratePurchasePermitResponse

Field	Type	Description
`PermitJSON`	`PurchasePermitV2` \| `PurchasePermitV3`	The purchase permit data. The version depends on sale configuration.
`Signature`	`string`	The signature of the purchase permit.

Core types

`EntityDetails`

Field	Type	Description
`Label`	`string`	Display name of the entity - for organizations, this will be the name of the organization, for users this will be the string “Yourself” because we do not share their real name.
`EntityID`	`string`	Used to lookup information by entity in the Sonar API. This ID is stable across sales for the querying oauth client.
`SaleSpecificEntityID`	`0x${string}`	Used to lookup information by entity on the sale contract. This ID is stable across clients for a given sale.
`EntityType`	`"user"` \| `"organization"`	The type of the entity.
`EntitySetupState`	`EntitySetupState`	The setup state of the entity. You can just check for `EntitySetupState.COMPLETE`, and link to the Sonar site if it’s incomplete. Optional: if you want to show more fine-grained information, see the EntitySetupState docs for suggested messages.
`SaleEligibility`	`SaleEligibility`	The eligibility state of the entity for the sale.
`InvestingRegion`	`InvestingRegion`	The investing region of the entity.

`MyProfileResponse`

Field	Type	Description
`EntityID`	`string`	The entity ID of the authenticated user.
`EmailAddress`	`string` \| `undefined`	The email address of the authenticated user, if available.

`EntitySetupState`

Enum with possible values: not-started

The entity has not started the setup process. The user should be linked to the Sonar site to continue.
Suggested message: “Entity not ready to invest — Please complete the entity setup process.”

in-progress

The entity has started the setup process, but it is not yet in review. The user should be linked to the Sonar site to continue.
Suggested message: “Entity not ready to invest — Please complete the entity setup process.”

ready-for-review

The entity has completed all current steps of the setup process and is ready to submit their data for review. The user should be linked to the Sonar site to continue.
Suggested message: “Entity not ready to invest — Please complete the entity setup process.”

in-review

The Sonar team is reviewing the entity.
Suggested message: “Entity not ready to invest — Please wait for the review to finish before you can make investments.”

failure

There is a problem with the entity setup. The user should be linked to the Sonar site so they can address the issues.
Suggested message: “Entity not ready to invest — Review your entity status in Sonar.”

failure-final

There is a problem with the entity setup, and the user is not able to address the issues.
Suggested message: “Entity not ready to invest — Review your entity status in Sonar.”

technical-issue

The setup is in a known technical issue state and we want the user to contact support if this happens.
Suggested message: “There’s an issue with your account — Please contact Sonar support to resolve it.”

complete

The entity has completed the setup process.
Suggested message: depends on the SaleEligibility value.

`SaleEligibility`

Once the entity has completed setup, you should check whether they are currently eligible for the sale. Possible values: eligible

The entity has completed setup and is eligible for the sale.
Suggested message: “Your entity is ready to participate in the sale.”

not-eligible

If the entity doesn’t meet sale requirements (e.g. resident of a blocked jurisdiction or accredited).
Suggested message: “Entity not qualified to invest.”

unknown-setup-incomplete

We don’t know whether the entity is eligible yet because they have not completed setup.
Suggested message: depends on the EntitySetupState value.

`InvestingRegion`

This can be useful if there are additional sale conditions that apply to US/EU entities, and you want to display this to users in the UI. Enum with possible values: unknown

We don’t currently know the entity’s region. This is only expected to be the case before KYC/KYB is completed.

us

The entity is located in the United States.

eu

The entity is located in the European Union.

other

The entity is located in another region.

`PrePurchaseFailureReason`

Enum with possible values: unknown

We don’t know why the entity is not ready to purchase. This is not expected to happen.
Suggested message: “An unknown error occurred — Please try again or contact support.”

wallet-risk

The wallet does not meet the configured risk thresholds.
Suggested message: “The connected wallet is not eligible for this sale. Connect a different wallet.”

max-wallets-used

The entity has reached the maximum number of wallets allowed for this sale.
Suggested message: “Maximum number of wallets reached — This entity can’t use the connected wallet. Use a previous wallet.”

requires-liveness

The entity requires a liveness check.
This is an expected case and the UI should not show an error; the UI should redirect the user to the LivenessCheckURL to complete a liveness check.

sale-not-active

The sale is not currently in a state where purchases are allowed.
Suggested message: “The sale is not currently active.”

wallet-not-linked

The connected wallet is not linked to the entity. This suggests there is a bug on your sale website because the entity ID should be looked up from the currently connected wallet address.

outside-time-window

The current time is outside the sale’s configured commitment window.
Suggested message: “The sale is not currently accepting commitments.”

`PurchasePermitV3`

The current permit version with time-gated access support.

Field	Type	Description
`SaleSpecificEntityID`	`0x${string}`	The sale-specific entity ID that the permit belongs to.
`SaleUUID`	`0x${string}`	The sale UUID that the permit belongs to, in hex format. The contract should verify this matches a hardcoded sale UUID.
`Wallet`	`0x${string}`	The wallet address. The sale contract should verify this matches the sender address.
`ExpiresAt`	`number`	Number representing the number of seconds since the Unix epoch. The sale contract should verify this is in the future.
`MinAmount`	`string`	The minimum amount the entity is allowed to commit.
`MaxAmount`	`string`	The maximum amount the entity is allowed to commit.
`MinPrice`	`number`	The minimum price the entity is allowed to bid at (for auctions).
`MaxPrice`	`number`	The maximum price the entity is allowed to bid at (for auctions).
`OpensAt`	`number`	Unix timestamp when the permit becomes valid (inclusive).
`ClosesAt`	`number`	Unix timestamp when the permit stops being valid (exclusive).
`Payload`	`0x${string}`	Contains arbitrary custom data (e.g., forced lockup preferences).

`PurchasePermitV2`

Legacy permit version without time-gated access. New sales should use V3.

Field	Type	Description
`SaleSpecificEntityID`	`0x${string}`	The sale-specific entity ID that the permit belongs to.
`SaleUUID`	`0x${string}`	The sale UUID that the permit belongs to, in hex format. The contract should verify this matches a hardcoded sale UUID.
`Wallet`	`0x${string}`	The wallet address. The sale contract should verify this matches the sender address.
`ExpiresAt`	`number`	Number representing the number of seconds since the Unix epoch. The sale contract should verify this is in the future.
`MinAmount`	`string`	The minimum amount the entity is allowed to commit.
`MaxAmount`	`string`	The maximum amount the entity is allowed to commit.
`MinPrice`	`number`	The minimum price the entity is allowed to bid at (for auctions).
`MaxPrice`	`number`	The maximum price the entity is allowed to bid at (for auctions).
`Payload`	`0x${string}`	Contains arbitrary custom data (e.g., forced lockup preferences).

`Commitment`

Represents a single commitment made to a sale.

Field	Type	Description
`CommitmentID`	`0x${string}`	Unique identifier for this commitment.
`SaleSpecificEntityID`	`0x${string}`	The sale-specific entity ID that made the commitment.
`PriceNumerator`	`string`	The numerator of the commitment price.
`PriceDenominator`	`string`	The denominator of the bid price fraction.
`PriceMicroUSD`	`string` \| `undefined`	The bid price expressed in micro USD.
`Amounts`	`WalletTokenAmount[]`	Array of amounts committed per wallet and token.
`CreatedAt`	`string`	ISO 8601 timestamp of when the commitment was created.
`ExtraRaw`	`0x${string}`	Hex-encoded raw `extraData` field from the ICommitmentDataReader interface.
`ExtraDataParsed`	`unknown`	Populated if our backend knows how to parse the `extraData` field.

The commitment price is only of interest for variable price sales - like auctions. It is expressed in terms of a PriceNumerator and PriceDenominator fraction. The price is in smallest units of the payment token per smallest unit of the offered token. You can divide the PriceNumerator by the PriceDenominator to get the price in decimal format, but you might lose precision. The PriceMicroUSD field is provided for convenience to avoid the need to divide the numerator and denominator. It is only set if the payment token is a USD stablecoin and the offered token decimals are configured. It contains the current commitment price in micro-USD for one human-readable offered token (1 human-readable token = 10^OfferedTokenDecimals smallest units). Warning: this could lose precision, so PriceNumerator and PriceDenominator should be used as the machine-readable value.

`WalletTokenAmount`

Represents an amount committed from a specific wallet using a specific token.

Field	Type	Description
`Wallet`	`0x${string}`	The wallet address that made this part of the commitment.
`Token`	`0x${string}`	The payment token address used.
`Amount`	`string`	The amount committed in token units.

`APIError`

Thrown if the Sonar API responds with a non-2xx status code or the response body fails to parse. Expected cases will be mentioned in the relevant function docs. Suggested message for unexpected errors: “Failed to load your data — Please try again or contact Sonar support.”

Field	Type	Description
`status`	`number`	The HTTP status code.
`code`	`string` \| `undefined`	A textual error code returned by the Sonar API. `undefined` if the response body fails to parse.
`details`	`any` \| `undefined`	The response body, if present.

Planning Your Sale

Integration Guides

Technical Features

Contract Reference

JS Reference

HTTP Reference

`SonarClient` functions

`readEntity`

`listAvailableEntities`

`myProfile`

`readEntityInvestmentHistory`

`fetchLimits`

`prePurchaseCheck`

`readCommitmentData`

`generatePurchasePermit`

Core types

`EntityDetails`

`MyProfileResponse`

`EntitySetupState`

`SaleEligibility`

`InvestingRegion`

`PrePurchaseFailureReason`

`PurchasePermitV3`

`PurchasePermitV2`

`Commitment`

`WalletTokenAmount`

`APIError`

​SonarClient functions

​readEntity

​listAvailableEntities

​myProfile

​readEntityInvestmentHistory

​fetchLimits

​prePurchaseCheck

​readCommitmentData

​generatePurchasePermit

​Core types

​EntityDetails

​MyProfileResponse

​EntitySetupState

​SaleEligibility

​InvestingRegion

​PrePurchaseFailureReason

​PurchasePermitV3

​PurchasePermitV2

​Commitment

​WalletTokenAmount

​APIError

`SonarClient` functions

`readEntity`

`listAvailableEntities`

`myProfile`

`readEntityInvestmentHistory`

`fetchLimits`

`prePurchaseCheck`

`readCommitmentData`

`generatePurchasePermit`

Core types

`EntityDetails`

`MyProfileResponse`

`EntitySetupState`

`SaleEligibility`

`InvestingRegion`

`PrePurchaseFailureReason`

`PurchasePermitV3`

`PurchasePermitV2`

`Commitment`

`WalletTokenAmount`

`APIError`