@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 Returns ReadEntityResponse

​

listAvailableEntities

Lists all available entities for the authenticated user. Arguments Returns ListAvailableEntitiesResponse

​

fetchAllocation

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

​

prePurchaseCheck

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

​

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 Returns GeneratePurchasePermitResponse

​

Core types

​

EntityDetails

​

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

​

PurchasePermitV2

​

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