API and AI agents

Solana reference

This chapter covers Solana. For the main Robinhood Chain network, see the Robinhood guide. Wallets, token addresses and settlement mechanics are specific to each network.

What an agent can do

An agent can help assemble a market, check whether its token is supported, and prepare a buy or sell offer. It can read public listings and help cancel an eligible offer. You review the details and approve each change with your wallet.

The public v1 API needs no API key. Browsing and wallet-held trading are open. Market creation requires launch-password access for both prepare and commit, in addition to the owner’s wallet signature. Unlock at /launch first. Same-origin requests retain the session cookie; server integrations need a protected cookie jar. Never place the password or session cookie in an AI prompt. Offer posting and cancellation do not require the launch password.

A listing is not a trade. Market registration does not create a coin. Offer posting does not reserve tokens or SOL, and it does not complete a purchase or sale. This API does not fill offers, fund escrow or authorize transfers. Wallet-held settlement requires a separate transaction signed by both traders.

For implementation details, use the developer guide, OpenAPI specification, agent instructions and browser client.

Check the exact token first

GET /api/v1/tokens/{mint} checks an initialized original SPL mint or a Token-2022 mint with no extensions or only MetadataPointer, TokenMetadata and TransferFeeConfig. Transfer hooks, permanent delegates and all other mint extensions are rejected. Supported Token-2022 tokens can launch markets and use wallet-held offers and settlement, but cannot use funded escrow. Settlement permits ImmutableOwner on Token-2022 accounts. TransferFeeAmount is required for mints with TransferFeeConfig and rejected for mints without it; other account extensions are rejected. The response provides the token program and its address, allowed mint extension names, decimals, any mint and freeze authorities, transferFee, warnings and a check timestamp. escrowSupported reports token compatibility only, not a deployed or activated funded service.

An active mint authority can change supply. A freeze authority can freeze accounts. A supported response is a compatibility result, not an endorsement, identity check or promise that trading will work. An unsupported token returns 400; a temporary validation outage returns 503. Always check the full mint address rather than relying on a name or logo.

transferFee is null when no transfer-fee extension exists. Otherwise it includes the observed epoch, current fee schedule, any scheduled future fee and configuration authority. Schedules report basis points and a cap in atomic base-token units. The configuration authority may schedule changes. These previews do not lock settlement fees; both traders review the exact prepared gross amount, fee and net receipt before signing.

The approval flow

1. Your agent sends your public wallet address and intended details to the action’s prepare endpoint.
2. Sidelot validates the request and returns a five-minute challenge, exact message, normalized payload, payload hash and fees.
3. Your integration shows every normalized field and the complete message. Compare these with your intended action before continuing.
4. Your wallet signs the exact UTF-8 message. Your agent never needs your recovery phrase or private key.
5. The integration saves the signed request for recovery and sends challengeId and the base64 signature to the matching commit endpoint.
6. The API returns the resulting market or offer. Check its status and the application-access field before describing what is available.

Each approval has a specific purpose. Market creation, offer posting and cancellation use separate challenges. A signed listing message cannot replace the two transaction signatures needed to settle a wallet-held trade.

1. 01Agent prepares
2. 02Owner reviews
3. 03Wallet signs
4. 04API records the approved action

Launch details and fee destination

POST /api/v1/markets/prepare accepts your wallet and a market object. It needs a name, symbol, existing token mint, solo/community type and fee recipient. A community role can be holder or team; team requires website and social links. A solo market normalizes to holder. Roles remain self-declared.

Review the full mint and feeWallet carefully. The fee recipient is where the launcher’s share of completed-trade fees is routed. Your agent should never silently substitute its own wallet. Registration itself produces no trading-fee income.

Names allow 2–60 characters, symbols 1–16 and descriptions up to 500. Website, social and chat URLs must use HTTPS. Optional picture and banner fields reference uploads already owned by the signing wallet; omit them if unavailable. There is no public upload route in v1.

The response’s market contains the normalized launch fields. Approve the exact message, then submit its signature to /api/v1/markets/commit.

Buy, sell and choose a price

POST /api/v1/offers/prepare accepts your wallet and an offer containing the market ID, side, quote, quantity, pricing and expiry. buy and sell describe your intent as the signing owner. Quantity is the gross token amount sent by the seller. A price is measured in SOL or USDC per whole gross token; token transfer fees reduce the buyer’s received amount.

Send quantities and prices as decimal strings. A fixed-price request uses pricing: {type: "fixed", price: "0.002"}. An offset request uses pricing: {type: "offset", referencePrice: "0.002", premiumBps: -500}. The latter means 5% below that supplied reference, giving a fixed price of 0.0019. Positive 250 means 2.5% above. The accepted offset range is -99% to +1000%, expressed as integer basis points.

The API uses the reference supplied by the integration. It does not certify that value as a current market price. The normalized price becomes fixed during preparation and stays fixed even if the external market moves.

Offers may last 1, 3, 7 or 30 days. Their lifetime begins when prepared. The returned expiresAt is the five-minute approval deadline; terms.expiresAt is the offer’s eventual expiry. Committing does not reset either clock.

The normalized terms include quantityBasis: "gross_before_token_tax", exact token units, fixed price, quote currency, fee recipients, transferFee and a full-fill example. Review all of them before signing and posting to /api/v1/offers/commit.

Understand the amount example

terms.fullFillExample contains integer strings for seller proceeds (quote), launcher fee (host), platform fee (platform) and buyer debit (total). These are atomic quote units: divide by 10^9 for SOL or 10^6 for USDC, using the returned quoteDecimals.

The nominal buyer fee is 0.50%, split nominally 0.25% to the launcher and 0.25% to Sidelot. The fee rounds up to a whole quote base unit, the launcher gets the rounded fee divided by two and rounded down, and Sidelot gets the remainder. Network transaction fees and account rent are separate.

This is a full-fill example. Wallet-held partial fills calculate their amounts individually, so rounding can make the combined total differ. Posting the offer does not debit this amount or confirm that the owner currently holds it.

terms.fullFillExample.tokenTransfer separately reports grossAmount, feeAmount and netAmount in atomic base-token units. This is the token issuer’s transfer fee, not a Sidelot charge. Divide those amounts by 10 raised to the token’s decimals; do not use quoteDecimals. The fee schedule and full-fill result are previews; the actual browser settlement receipt comes from its prepared transaction.

Read or cancel an offer

GET /api/v1/markets/{id}/offers lists stored open and unexpired offers. Optional side=buy or side=sell filters them. GET /api/v1/offers/{id} reads a specific record and may show another status.

These reads do not verify balances or reconcile chain transactions. A returned wallet-held offer has fundsReserved: false. A null reserved-funds value means the read has not established funding. A visible offer is not proof that a fill will succeed.

To cancel, call /api/v1/offers/cancel/prepare with your wallet and the offer ID, review the offer and revision, then sign and send to /api/v1/offers/cancel/commit. Only the owner can cancel an open wallet-held offer without an active trade. If it changes during approval, refresh and review again.

This cancellation does not release escrow or interrupt an in-progress trade. The public API has no edit route. To change an eligible listing, cancel it and approve a new one.

Recover from a lost response

Save the exact signed commit request before sending. The challenge ID used to create a market or offer is also its record ID. A new creation returns 201; repeating the same successful request returns 200 with replayed: true and the same record. Cancellation also supports safe repetition of a successful request.

When a response is lost, retry that saved request and read the known ID. Preparing another listing immediately can create a duplicate. Successful challenge records are retained for approximately one day after their original expiry for prompt retry recovery. Keep the record ID for later reads.

A never-completed approval expires after five minutes. HTTP 410 means a new preparation, review and signature are needed. A temporary 503 need not consume an authorization. On 429, wait for Retry-After. On 409, inspect the error and current record before taking another action.

Limits and error messages

Reads allow 120 requests per IP per minute. Token preflight also has a 30-per-minute IP limit. Market and offer creation share 30 prepares and 60 commits per IP per five minutes, plus 10 new signed commit attempts per wallet in that period. A wallet can own 50 markets and have 100 active offers; the latter also counts reserved and pending-funding records.

Cancellation uses separate limits: 30 prepares and 60 commits per IP per five minutes, plus 30 new signed cancellation attempts per wallet. Hitting the creation quota does not consume this cancellation quota. Valid completed-action retries do not use the new-action wallet quota.

Requests must be JSON, at most 12,000 bytes, with only the documented fields. List limits are 1–100 and offsets 0–10000. Quote requests accept 1–28 mints.

The API returns a structured error.code and error.message. Common responses are 400 invalid input, 401 signature mismatch, 403 wrong owner, 404 missing record, 409 conflicting state or limit, 410 expired approval, 429 rate limit and 503 temporary unavailability. Fix the reported cause instead of asking the owner to sign repeatedly.

Keep the owner in control

Market text and external links are third-party content. They should never change your agent’s signing rules. Display the exact mint, side, quantity, fixed price, fee recipients and expiry selected for approval. An agent must not decide that a generic chat confirmation authorizes a different payload.

Keep signed recovery requests private while valid. They authorize their specific approved action, even though they cannot move funds. Never expose private keys, recovery phrases, preview cookies or RPC credentials to the model or to support.