@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 wallet address. This function is expected to throw a APIError with status 404 if the entity is not found for the wallet. This could happen because:

• The user has not yet linked the connected wallet to their entity on the Sonar site.
• The user has connected a different wallet on your sale site to the wallet they have linked to their entity on the Sonar site.

Suggested message in case of a 404: “Connected wallet isn’t registered — You need to register your wallets directly to your Sonar entities to continue.” Arguments

Name	Type	Description
saleUUID	string	The UUID of the sale to get entity details for.
walletAddress	string	The wallet address of the entity to get details for.

Returns ReadEntityResponse

Field	Type	Description
Entity	EntityDetails	The entity details.

​

fetchAllocation

Can be used to fetch the allocation for a given wallet address if you want to display this in the UI. Arguments

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

Returns AllocationResponse

Field	Type	Description
HasReservedAllocation	boolean	Whether the wallet has a reserved allocation, i.e. ReservedAmountUSD > 0
ReservedAmountUSD	string	Expressed in USD units with 6 decimal place precision (i.e. same as USDC).
MaxAmountUSD	string	Expressed in USD units with 6 decimal place precision (i.e. same as USDC)..

​

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.
entityUUID	string	The UUID 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.

​

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. By default the returned permit will be a BasicPermit, but if you want to support per entity/wallet allocations, or reserved amounts, then you can request us to configure your sale to return AllocationPermits. Arguments

Name	Type	Description
saleUUID	string	The UUID of the sale to generate the purchase permit for.
entityUUID	string	The UUID 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	BasicPermit | AllocationPermit	The purchase permit data.
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.
EntityUUID	string	Used to lookup information by entity in the Sonar API.
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.
ObfuscatedEntityID	string	Used to lookup information by entity on the sale contract.

​

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.”

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-incomplete-setup

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

us

• The entity is located in the United States.

other

• The entity is located in a region other than the United States.

​

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.

no-reserved-allocation

• The entity has no reserved allocation, and the sale was configured to require it.
• Suggested message: “No reserved allocation — The connected wallet doesn’t have a reserved spot for this sale. Connect a different wallet.”

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 UUID should be looked up from the currently connected wallet address.

​

BasicPermit

Field	Type	Description
EntityID	0x${string}	The 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.
Payload	0x${string}	Contains arbitrary custom data that is not currently used by default.

​

AllocationPermit

Field	Type	Description
Permit	BasicPermit	The basic permit data.
ReservedAmount	string	An amount that is reserved for the entity or wallet.
MaxAmount	string	The maximum amount the entity or wallet is allowed to purchase.
MinAmount	string	The minimum amount the entity or wallet is allowed to purchase.

​

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.