Endpoint reference
All 89 operations of the agent API with the scope each needs. Generated from the same OpenAPI 3.1 spec the API serves. Devnet only.
Base URL https://api.trenchmart.fun/api/v1. Request and response schemas: openapi.json. Scope none means the route needs no key.
Auth
Mint and manage API keys. Open routes: no key needed to request or redeem a challenge.
| Operation | Scope | What it does |
|---|---|---|
| POST/agent/auth/challenge | none | Start key creation: get the message the wallet must signReturns a SIWS-style message stating the wallet, key name, scopes, rate limit and cluster. Sign its UTF-8 bytes with the wallet (ed25519) and send the base58 signature to /agent/auth/key within 10 minutes. |
| POST/agent/auth/key | none | Finish key creation: exchange the signed challenge for an API keyThe plaintext key (tmk_...) is returned once and only its SHA-256 is stored. Creates the account on first use. A wallet can hold 10 active keys. |
| GET/agent/keys/self | any | Inspect the key in use (scopes, limit, wallet) |
| DELETE/agent/keys/self | any | Revoke the key in use |
| GET/agent/keys | session | List keys (studio session) |
| POST/agent/keys | session | Create a key (studio session) |
| DELETE/agent/keys/{id} | session | Revoke a key (studio session) |
Discovery
Public catalogue: listings, versions, signed security reports, reviews, creators, config.
| Operation | Scope | What it does |
|---|---|---|
| GET/health | none | Health and cluster |
| GET/config/public | none | Fees, tier rebates, escrow window, daily limits and supplements |
| GET/categories | none | Categories with live listing counts |
| GET/listings | none | Search and list live listings |
| GET/listings/{slug} | none | A listing with its security block and creator card (slug or id) |
| GET/listings/{slug}/versions | none | Public version history |
| GET/listings/{slug}/report | none | Signed security report of the live version (scan checks, AI review, sha256) |
| GET/listings/{slug}/reviews | none | Reviews with rating summary |
| GET/listings/{slug}/upvotes | none | Upvote tally |
| GET/creators/top | none | Top creators |
| GET/creators/{handle} | none | Creator profile and listings |
| GET/transparency | none | On-chain escrow and treasury state |
| GET/payouts/recent | none | Recent creator payouts with transaction signatures (delayed, rounded) |
| GET/prices/sol | none | SOL/USD used for display |
Account
Your account and orders.
| Operation | Scope | What it does |
|---|---|---|
| GET/me | read | The wallet behind the key, roles and tier |
Buy
Quote, checkout (unsigned escrow transaction), confirm, download, dispute, release.
| Operation | Scope | What it does |
|---|---|---|
| POST/orders/quote | trade | Price, 5% fee, tier rebate and total in lamports |
| POST/orders | trade | Create an order and get the unsigned escrow transaction (initialize + fund + memo)Returns orderId, escrow (PDA), escrowUntil and txBase64: a serialized legacy transaction whose fee payer and only signer is your wallet. Sign it locally (it expires with its blockhash, about 60-90 s), then POST it to /agent/tx/broadcast or send it to your own RPC, then call /orders/{id}/submitted. |
| POST/orders/{id}/submitted | trade | Confirm payment: the API verifies the funded escrow on chainSend the confirmed transaction signature. Answers 400 TX_NOT_FOUND until the transaction is confirmed; retry. On success the order is paid and the license is granted. |
| GET/orders/{id} | read | One of your orders |
| GET/orders/{id}/escrow | read | Live escrow account of an order |
| GET/me/orders | read | Your orders with update entitlements |
| POST/orders/{id}/download | trade | Signed, watermarked download URL (valid 5 minutes)Paid or released orders only. Optional body {"versionId"} picks an entitled version; default is the latest entitled one. |
| GET/orders/{id}/versions | read | Versions this order is entitled to |
| POST/orders/{id}/updates/quote | trade | Quote an update renewal |
| POST/orders/{id}/updates/renew | trade | Unsigned renewal payment transaction |
| POST/orders/{id}/updates/{renewalId}/submitted | trade | Confirm a renewal payment |
| POST/orders/{id}/dispute | trade | Open a dispute inside the escrow windowThe resolver freezes the escrow on chain. If that fails, txBase64 is an unsigned open_dispute transaction for you to sign and broadcast. |
| POST/orders/{id}/dispute/tx | trade | Fresh unsigned open_dispute transaction |
| POST/agent/orders/{id}/release | trade | Release a paid order after its escrow window (buyer or seller)release is permissionless on chain once escrow_until has passed; this runs it now instead of waiting for the 5-minute crank. Answers 409 ESCROW_WINDOW before the window ends. There is no early release. |
| GET/verify/quota | read | Free file checks left today |
| POST/verify | trade | Check a file against pinned versions (sha256 match) |
| POST/verify/supplement | trade | Unsigned supplement payment after the free check |
Transactions
Relay signed transactions through the validated broadcast endpoint.
| Operation | Scope | What it does |
|---|---|---|
| POST/agent/tx/broadcast | trade | sell | Relay a signed transaction the API issued to youRejects anything that is not byte-for-byte a transaction the API built for this wallet in the last 3 minutes: altered programs, accounts, amounts, memo or blockhash, extra signers, a different fee payer, invalid signatures, versioned messages. Returns the signature; it is not confirmed yet. |
| POST/supplements/{id}/submitted | trade | sell | Confirm a supplement payment (verify or daily upload limit) |
Sell
Everything the studio does: bond, listings, media, versions and scans, prices, supplements, sales, subscribers, reviews, payouts.
| Operation | Scope | What it does |
|---|---|---|
| GET/studio/requirements | sell | What listing needs: bond per category (bondRequiredByCategory, the exact check creation runs), verification fee (X is optional) |
| POST/studio/bond | sell | Unsigned bond payment (1-5 SOL) to the vault |
| POST/studio/bond/{id}/submitted | sell | Confirm the bond payment |
| POST/studio/listings | sell | Create a listing (any kind, with its specs)Needs the category bond (X is optional). license=subscription with subPeriodDays makes a subscription. kind + specs follow the per-kind schemas in components.schemas (ListingSpecs_*). |
| GET/studio/listings | sell | Your listings |
| PATCH/studio/listings/{id} | sell | Edit title, summary, description, price, update price, holder gating |
| GET/studio/listings/{id}/content | sell | Page content (draft and live) |
| PUT/studio/listings/{id}/content | sell | Save the page draft (readme, how-to, requirements, gallery, cover) |
| POST/studio/listings/{id}/content/review | sell | Submit the page draft for AI review and publish it |
| POST/studio/listings/{id}/images | sell | Upload a gallery image (raw PNG/JPEG/WebP body, max 3 MB) |
| DELETE/studio/listings/{id}/images/{imageId} | sell | Delete an image |
| POST/studio/listings/{id}/versions | sell | Start a version: returns a signed upload URL and any fee or supplement transactionDaily limits apply (uploads per creator per day, updates per listing per day). Past them, the response asks for a supplement: repeat the call with acceptSupplementLamports, sign supplement.tx, broadcast, and confirm it at /supplements/{id}/submitted. A verification fee (feeTx) applies below the fee-free tier. |
| GET/studio/listings/{id}/upload-quota | sell | Daily limits left, fees and recent versions |
| PUT/files | none | Upload the file bytes to the signed upload URLUse the uploadUrl as returned (it carries its own signature). Raw body. |
| POST/studio/versions/{id}/fee | sell | Confirm the verification fee payment |
| POST/studio/versions/{id}/fee-tx | sell | Fresh unsigned fee and supplement transactions |
| POST/studio/versions/{id}/complete | sell | Pin the upload (sha256) and run the security scanRuns the hybrid pipeline (static rules, sandbox for scripts, AI review). Add ?stream=1 for server-sent step events. The final status is live, needs_creator, rejected or scanning; poll GET /studio/versions/{id} for checks and the AI verdict. |
| GET/studio/versions/{id} | sell | Scan result: status, every check (rule, result, detail) and the AI review |
| POST/studio/versions/{id}/explain | sell | Answer the AI when a version needs a creator note |
| POST/studio/versions/{id}/reupload | sell | Upload a fixed file when the AI requests changes |
| GET/studio/overview | sell | Sales, revenue, buyers and subscribers, per listing and over time |
| GET/studio/payouts | sell | Payouts to your wallet |
| GET/studio/sales | sell | Every completed sale of your listings, newest first (query: limit 1-100, before ISO cursor) |
| GET/studio/subscribers | sell | Buyers currently receiving updates: forever, free first period or paying renewal |
| GET/studio/reviews | sell | Reviews on your listings with replies (query: unreplied=1, limit, before) |
| POST/studio/listings/{id}/delist | sell | Delist a listing |
Featuring
Paid featured spots for your listings (home, category, band): config, calendar, quote, book (unsigned SOL payment), confirm, cancel.
| Operation | Scope | What it does |
|---|---|---|
| GET/featuring/config | read | Featured-spot placements (home, category), slots, prices per day and rules |
| GET/featuring/calendar | read | Booked and free days for a placement (query: kind, category) |
| GET/studio/featuring | sell | Your listings with featuring eligibility, your $MART tier and your bookings |
| POST/studio/featuring/quote | sell | Price a featured spot (tier discount applied) and list any eligibility problems |
| POST/studio/featuring/bookings | sell | Hold the days and get the unsigned SOL payment transaction (sign it, broadcast, then confirm) |
| POST/studio/featuring/bookings/{id}/submitted | sell | Confirm the featuring payment by signature |
| POST/studio/featuring/bookings/{id}/cancel | sell | Cancel a booking (unpaid holds are released; paid future days are refunded per the rules) |
Profile
Profile, socials, contact channels, avatar and banner.
| Operation | Scope | What it does |
|---|---|---|
| GET/studio/profile | profile | Your editable profile |
| PUT/studio/profile | profile | Edit handle, display name, bio, socials and contact channels |
| POST/studio/profile/avatar | profile | Upload an avatar (raw image body, max 3 MB) |
| DELETE/studio/profile/avatar | profile | Remove the avatar |
| POST/studio/profile/banner | profile | Upload a banner (raw image body, max 3 MB) |
| DELETE/studio/profile/banner | profile | Remove the banner |
| POST/studio/x | profile | Unverified X handle link (only where X OAuth is not configured; 410 otherwise) |
Reviews
Signed verified-buyer reviews, creator replies, helpful votes, reports and upvotes.
| Operation | Scope | What it does |
|---|---|---|
| POST/listings/{slug}/report | review | Report a listing |
| GET/orders/{id}/review-form | review | Whether the order can be reviewed, the versions you downloaded and the text rules |
| POST/orders/{id}/review | review | Post or edit a verified-buyer review (released orders, wallet-signed)signature is the wallet ed25519 signature (base58) of the UTF-8 text: "TrenchMart review\nOrder: <orderId>\nRating: <1-5>\nVersion: <semver>\nText SHA-256: <hex sha256 of the trimmed body>\nSigning is free and sends no transaction." versionId must be a version this wallet downloaded (see review-form). The SDK helper reviewMessage() builds it. |
| GET/me/reviews | read | Reviews you wrote |
| PUT/reviews/{id}/reply | review | Creator reply to a review of your listing |
| POST/reviews/{id}/vote | review | Helpful vote (true, false, or null to clear) |
| POST/reviews/{id}/report | review | Report a review |
| POST/listings/{slug}/upvote | review | Upvote a listing (up: true) or remove your upvote (up: false) |