@amn/sdk · API reference
@amn/sdk
One package that lets code or an AI agent run a shop end to end — add products (کالا), manage inventory, make offers, and, as a buyer, open requests, pay through escrow, and confirm delivery. Built directly on the real AMN API.
.sellerThe complete shop surface — catalog, inventory, offers, orders, settings, finance, disputes (~90 operations).
.buyerDiscovery, requests, negotiation, escrow payment, delivery, disputes.
agent/The same operations as Claude tool-use tools — hand them to a model.
No dependencies
Node 20+ or browser
Types included
Quick Start (from code)
quickstart.ts
import { createAmnClient } from '@amn/sdk';
const amn = createAmnClient({ baseUrl: 'https://multi.amn.gg' });
await amn.login('seller@amn.gg', '••••••');
// Seller: add a product (کالا) and publish it
const p = await amn.seller.addProduct({ title: 'گیفت کارت استیم ۲۰$', price: 22, currency: 'USDT' });
await amn.seller.toggleProduct(p.id);
// Buyer: open a request
const req = await amn.buyer.createRequest({ title: 'همون گیفت کارت', budget: 25 });Quick Start (hand it to an agent)
agent.ts
import { createAmnClient } from '@amn/sdk';
import { agentTools, runTool } from '@amn/sdk/agent';
const amn = createAmnClient({ baseUrl: 'https://multi.amn.gg' });
await amn.login('seller@amn.gg', '••••••');
const tools = agentTools('seller'); // pass to the Messages API
const output = await runTool(amn, { name: 'seller_add_product', input: { title: '…', price: 22 } });Tip — The full loop lives in
examples/agent-runs-shop.ts — pass agentTools(scope) to the Messages API and feed each tool_use block to runTool.Concepts
One client = one session
A client holds one bearer token. Create it, log in (or pass a token), then use .seller / .buyer.
Base URL
You pass the host (https://multi.amn.gg); the SDK appends /api itself. A trailing slash is tolerated.
Auth
login() stores the token in memory. On a 401, the SDK makes one refresh attempt (/auth/refresh-token), then retries the call once.
Return shape
Methods unwrap the platform’s { data } envelope. Catalog reads normalise to a typed Product with a raw escape hatch that holds the untouched backend object.
Errors
Any non-2xx throws AmnApiError (see below).
Authentication
login() stores the token in memory → on a 401 the SDK makes one refresh attempt (/auth/refresh-token) via the httpOnly cookie (browser) or a supplied refreshToken (server/agent) → retries the call once.
Note — The token lives in memory only. In the browser the refresh rides an httpOnly cookie; on a server/agent, supply
refreshToken in the client options.createAmnClient(options)
Returns an AmnClient.
OPTION
TYPE
PURPOSE
baseUrlrequired
string
Host, e.g. https://multi.amn.gg. SDK appends /api.
accessToken
string
Pre-obtained bearer token — skip login().
refreshToken
string
Long-lived token for server/agent use; enables one refresh on 401.
onToken
(t: string | null) => void
Called whenever the token changes — persist it if you like.
fetch
typeof fetch
Override global fetch (tests, proxies, older runtimes).
headers
Record<string,string>
Extra headers merged into every request.
shopId
string
Default ?shopId= applied to shop-scoped reads.
Client methods
METHOD
RETURNS
NOTES
login(email, password)
Promise<AuthResult>
Stores the token; throws if none returned.
whoami()
Promise<unknown>
Current identity — id, role, tenant (/auth/profile).
setToken(token | null)
void
Set/clear the bearer manually.
logout()
void
Clears the in-memory token.
.seller
SellerApi
Seller namespace.
.buyer
BuyerApi
Buyer namespace.
.http
HttpClient
Escape hatch for raw get/post/put/del against any route.
Errors — AmnApiError
Every non-2xx response throws AmnApiError.
errors.ts
import { AmnApiError } from '@amn/sdk';
try {
await amn.seller.addProduct({ title: '…' });
} catch (e) {
if (e instanceof AmnApiError) {
e.status; // number — HTTP status
e.path; // string — the route that failed
e.body; // unknown — parsed error payload
e.message; // backend message/error, or "<status> <statusText>"
}
}statusnumber — HTTP status.
pathstring — The route that failed.
bodyunknown — Parsed error payload.
messagestring — Backend message/error, or "<status> <statusText>".
Types
AmnClientOptions
The constructor options above.
AuthResult
{ accessToken, user: { id, role, tenantId, … } }.
Product
{ id, title, description?, price?, currency?, status?, …, raw }.
ProductInput
Create/update body; pack fields under verticalFields; open [k: string]: unknown.
PurchaseRequest / Offer / Paginated<T>
Pragmatic shapes, each with a raw escape hatch.
Role
'buyer' | 'seller' | 'admin' | 'support'.
Note — The SDK types only the fields you reason about; everything else lives on
raw. Never assume a field is absent just because it is not on the type.SELLER API — run a shop (کالا · فاکتور)
Identity & Account
Who you are, your profile, and where earnings are paid.
6 methods
METHOD
DOES
ROUTE
whoami()
Current identity (id, role, tenant).
GETGET /auth/profile
getProfile()
Full user profile.
GETGET /user/profile
updateProfile(patch)
Edit profile.
POSTPOST /auth/update-profile
changePassword({currentPassword, newPassword})
Change password.
POSTPOST /auth/change-password
getPayoutWallet()
Payout destination (org-scoped, one per account).
GETGET /user/wallet-address
setPayoutWallet(address)
Set payout destination.
POSTPOST /user/wallet-address
GETGET /auth/profile
whoami()
Current identity (id, role, tenant).
GETGET /user/profile
getProfile()
Full user profile.
POSTPOST /auth/update-profile
updateProfile(patch)
Edit profile.
POSTPOST /auth/change-password
changePassword({currentPassword, newPassword})
Change password.
GETGET /user/wallet-address
getPayoutWallet()
Payout destination (org-scoped, one per account).
POSTPOST /user/wallet-address
setPayoutWallet(address)
Set payout destination.
Note — Payout is org-scoped — one destination per account, not per shop.
Becoming a seller
فروشنده شو4 methods
METHOD
DOES
ROUTE
getApplication()
Own application (404 = never applied).
GETGET /seller-applications/me
applyAsSeller(input)
Submit an application.
POSTPOST /seller-applications
resubmitApplication(input)
Re-submit after needs_info.
PUTPUT /seller-applications/me
withdrawApplication()
Withdraw.
POSTPOST /seller-applications/me/withdraw
GETGET /seller-applications/me
getApplication()
Own application (404 = never applied).
POSTPOST /seller-applications
applyAsSeller(input)
Submit an application.
PUTPUT /seller-applications/me
resubmitApplication(input)
Re-submit after needs_info.
POSTPOST /seller-applications/me/withdraw
withdrawApplication()
Withdraw.
Catalog — products
کالاA shop's catalog. کالا — the product a buyer orders — is the unit everything else hangs off. Call itemSchema() before addProduct() so the vertical pack's fields validate.
12 methods
METHOD
DOES
ROUTE
listProducts(query?)
List own products → Product[].
GETGET /marketplace/request-templates
getProduct(id)
One product → Product.
GETGET …/request-templates/:id
itemSchema()
The vertical-pack form descriptor for this shop. Call before addProduct.
GETGET …/request-templates/item-schema
getVerticalFields(id)
Stored pack values + conformance.
GETGET …/request-templates/:id/vertical-fields
addProduct(input)
Add a product → Product. Pack values under input.verticalFields.
POSTPOST …/request-templates
updateProduct(id, patch)
Edit (partial) → Product.
PUTPUT …/request-templates/:id
deleteProduct(id)
Remove.
DELETEDELETE …/request-templates/:id
toggleProduct(id)
Publish / unpublish → Product.
POSTPOST …/request-templates/:id/toggle-status
importProducts(rows)
Bulk import (CSV/XLSX rows).
POSTPOST …/request-templates/import
productStats()
Catalog stats.
GETGET …/request-templates/stats
linkProductGroup(id, payload) / unlinkProductGroup(id)
Combined listings (کالاهای همخانواده).
POSTPOST|DELETE …/request-templates/:id/linked-group
GETGET /marketplace/request-templates
listProducts(query?)
List own products → Product[].
GETGET …/request-templates/:id
getProduct(id)
One product → Product.
GETGET …/request-templates/item-schema
itemSchema()
The vertical-pack form descriptor for this shop. Call before addProduct.
GETGET …/request-templates/:id/vertical-fields
getVerticalFields(id)
Stored pack values + conformance.
POSTPOST …/request-templates
addProduct(input)
Add a product → Product. Pack values under input.verticalFields.
PUTPUT …/request-templates/:id
updateProduct(id, patch)
Edit (partial) → Product.
DELETEDELETE …/request-templates/:id
deleteProduct(id)
Remove.
POSTPOST …/request-templates/:id/toggle-status
toggleProduct(id)
Publish / unpublish → Product.
POSTPOST …/request-templates/import
importProducts(rows)
Bulk import (CSV/XLSX rows).
GETGET …/request-templates/stats
productStats()
Catalog stats.
POSTPOST|DELETE …/request-templates/:id/linked-group
linkProductGroup(id, payload) / unlinkProductGroup(id)
Combined listings (کالاهای همخانواده).
Tip — linkProductGroup() ties کالاهای همخانواده together so a buyer sees one card with variants.
Inventory, Pools & Vaults
Digital goods — the codes and keys orders draw from, plus pools and hot/cold vaults.
21 methods
METHOD
DOES
ROUTE
listInventory(query?) / addStock(item)
List / add codes/keys.
GETGET|POST /digital-goods/inventory
getInventoryItem(id) / updateInventoryItem(id, patch) / deleteInventoryItem(id)
One stock item.
GET…/inventory/:id
listInventoryProducts() / getInventoryProduct(templateId)
Product-level inventory.
GET/digital-goods/inventory-products…
linkInventoryPool(templateId, payload)
Link a product to a pool.
POSTPOST …/inventory-products/:templateId/link-pool
listPools(query?) / createPool(input)
Inventory pools.
GETGET|POST /digital-goods/pools
deliverDigital(requestId, payload)
Releases goods — deliver to a paid order.
POSTPOST /digital-goods/orders/:requestId/deliver
getOrderInventory(requestId)
Stock pickable for one order's SKU.
GETGET …/orders/:requestId/inventory
listVaults() / createVault(input) / getVault(vaultId)
Hot/cold key vaults.
GETGET|POST /digital-goods/vaults…
getRestockRecommendation(vaultId) / setRestockPolicy(vaultId, policy)
Restock.
GETGET|PUT …/vaults/:vaultId/restock-*
listColdItems(vaultId) / listVaultTransfers(vaultId)
Cold custody — reads.
GET…/vaults/:vaultId/cold-items, …/vaults/:vaultId/transfers
importColdItems(vaultId, items)
Add cold-storage items to a vault.
POSTPOST …/vaults/:vaultId/cold-items/import
replaceVaultKey(vaultId, payload)
Rotates the vault's custody signing key.
POSTPOST …/vaults/:vaultId/key/replace
GETGET|POST /digital-goods/inventory
listInventory(query?) / addStock(item)
List / add codes/keys.
GET…/inventory/:id
getInventoryItem(id) / updateInventoryItem(id, patch) / deleteInventoryItem(id)
One stock item.
GET/digital-goods/inventory-products…
listInventoryProducts() / getInventoryProduct(templateId)
Product-level inventory.
POSTPOST …/inventory-products/:templateId/link-pool
linkInventoryPool(templateId, payload)
Link a product to a pool.
GETGET|POST /digital-goods/pools
listPools(query?) / createPool(input)
Inventory pools.
POSTPOST /digital-goods/orders/:requestId/deliver
deliverDigital(requestId, payload)
irreversibleReleases goods — deliver to a paid order.
GETGET …/orders/:requestId/inventory
getOrderInventory(requestId)
Stock pickable for one order's SKU.
GETGET|POST /digital-goods/vaults…
listVaults() / createVault(input) / getVault(vaultId)
Hot/cold key vaults.
GETGET|PUT …/vaults/:vaultId/restock-*
getRestockRecommendation(vaultId) / setRestockPolicy(vaultId, policy)
Restock.
GET…/vaults/:vaultId/cold-items, …/vaults/:vaultId/transfers
listColdItems(vaultId) / listVaultTransfers(vaultId)
Cold custody — reads.
POSTPOST …/vaults/:vaultId/cold-items/import
importColdItems(vaultId, items)
Add cold-storage items to a vault.
POSTPOST …/vaults/:vaultId/key/replace
replaceVaultKey(vaultId, payload)
irreversibleRotates the vault's custody signing key.
Irreversible — deliverDigital() releases the goods to the order. Gate it behind a human approve in any UI.
Browse buyer requests
5 methods
METHOD
DOES
ROUTE
browseRequests(query?)
Open requests to offer on.
GETGET …/purchase-requests
getRequest(id)
One request.
GETGET …/purchase-requests/:id
searchRequests(query?)
Search.
GETGET …/purchase-requests/search
requestWorkflow(id)
Workflow steps.
GETGET …/purchase-requests/:id/workflow-steps
requestStats()
Stats.
GETGET …/purchase-requests/stats
GETGET …/purchase-requests
browseRequests(query?)
Open requests to offer on.
GETGET …/purchase-requests/:id
getRequest(id)
One request.
GETGET …/purchase-requests/search
searchRequests(query?)
Search.
GETGET …/purchase-requests/:id/workflow-steps
requestWorkflow(id)
Workflow steps.
GETGET …/purchase-requests/stats
requestStats()
Stats.
Offers & Negotiation
11 methods
METHOD
DOES
ROUTE
listOffers(requestId)
Offers on a request.
GETGET …/purchase-requests/:id/offers
makeOffer(requestId, offer)
Offer on a buyer's request.
POSTPOST …/purchase-requests/:id/offers
myOffers(sellerId?)
The shop's own offers (resolves own id).
GETGET …/offers/seller/:sellerId
updateOffer(offerId, patch)
Edit an offer.
PUTPUT …/offers/:id
confirmAgreement(offerId)
Countersign the pre-payment summary so the buyer can pay.
POSTPOST …/offers/:id/confirm-agreement
withdrawOffer(offerId, reason?)
Withdraw.
POSTPOST …/offers/:id/status
getNegotiation(offerId) / startNegotiation(offerId, msg)
Negotiation thread.
GETGET|POST …/offers/:offerId/negotiations
counterOffer(offerId, price, note?) / acceptNegotiation / rejectNegotiation
Bargain.
POST…/offers/:offerId/negotiations/*
GETGET …/purchase-requests/:id/offers
listOffers(requestId)
Offers on a request.
POSTPOST …/purchase-requests/:id/offers
makeOffer(requestId, offer)
Offer on a buyer's request.
GETGET …/offers/seller/:sellerId
myOffers(sellerId?)
The shop's own offers (resolves own id).
PUTPUT …/offers/:id
updateOffer(offerId, patch)
Edit an offer.
POSTPOST …/offers/:id/confirm-agreement
confirmAgreement(offerId)
Countersign the pre-payment summary so the buyer can pay.
POSTPOST …/offers/:id/status
withdrawOffer(offerId, reason?)
Withdraw.
GETGET|POST …/offers/:offerId/negotiations
getNegotiation(offerId) / startNegotiation(offerId, msg)
Negotiation thread.
POST…/offers/:offerId/negotiations/*
counterOffer(offerId, price, note?) / acceptNegotiation / rejectNegotiation
Bargain.
Orders, Delivery & Invoices
فاکتور10 methods
METHOD
DOES
ROUTE
listOrders(query?)
Seller sales ledger.
GETGET /orders/selling
getOrder(orderId)
One order.
GETGET /orders/:orderId
downloadInvoice(orderId)
Invoice (فاکتور) PDF bytes → {data, contentType, filename}.
GETGET /orders/:orderId/invoice
setDelivery(requestId, info)
Set/adjust delivery info.
POSTPOST …/purchase-requests/:id/delivery
generateDeliveryCode(requestId) / regenerateDeliveryCode(requestId)
Hand-off code.
POSTPOST …/delivery-code/generate|regenerate
getDeliveryCode / deliveryCodeStatus / deliveryAttempts
Code status.
GETGET …/delivery-code…
deliveryStats()
Delivery stats.
GETGET /marketplace/delivery/stats
GETGET /orders/selling
listOrders(query?)
Seller sales ledger.
GETGET /orders/:orderId
getOrder(orderId)
One order.
GETGET /orders/:orderId/invoice
downloadInvoice(orderId)
Invoice (فاکتور) PDF bytes → {data, contentType, filename}.
POSTPOST …/purchase-requests/:id/delivery
setDelivery(requestId, info)
Set/adjust delivery info.
POSTPOST …/delivery-code/generate|regenerate
generateDeliveryCode(requestId) / regenerateDeliveryCode(requestId)
Hand-off code.
GETGET …/delivery-code…
getDeliveryCode / deliveryCodeStatus / deliveryAttempts
Code status.
GETGET /marketplace/delivery/stats
deliveryStats()
Delivery stats.
Shop settings, Storefronts & Multi-shop
One shop or many under an org (tenant): settings, custom domains, Telegram bots, storefronts and vertical packs.
36 methods
METHOD
DOES
ROUTE
getShopSettings() / updateShopSettings(patch)
Shop settings.
GETGET|PUT /marketplace/shop/settings
getSellerShopSettings(sellerId)
Another shop's public settings.
GETGET …/shop/settings/:sellerId
myTenant() / myMemberships() / createTenant(input)
Org self-service.
GET/tenants…
listDomains / addDomain / verifyDomain / deleteDomain
Custom domains.
GET/tenants/:tenantId/domains…
registerBot / botClaimLink / reconfigureBot / deleteBot
Telegram bot.
POST/tenants/:tenantId/telegram/bot…
listBotShops / bindBotToShop / setBotShopDefault / unbindBotFromShop
Bot ↔ shop.
GET…/telegram/bots/:botId/shops…
listShops / createShop / getShop / updateShop / deleteShop
Shops under an org.
GET/tenants/:tenantRef/shops…
listStorefronts / createStorefront / getStorefront / updateStorefront / deleteStorefront
Storefronts.
GET/tenants/:tenantRef/storefronts…
listStorefrontBindings / bindShopToStorefront / updateStorefrontBinding / unbindShopFromStorefront
Bind shops to a storefront.
GET…/storefronts/:storefrontId/shops…
listVerticals / getShopVerticalVersion / upgradeShopVertical
Vertical packs.
GET…/verticals, …/shops/:shopId/vertical-version
shopRevenue(ref, shopId?)
Shop ledger totals.
GETGET …/finance/shop-revenue
GETGET|PUT /marketplace/shop/settings
getShopSettings() / updateShopSettings(patch)
Shop settings.
GETGET …/shop/settings/:sellerId
getSellerShopSettings(sellerId)
Another shop's public settings.
GET/tenants…
myTenant() / myMemberships() / createTenant(input)
Org self-service.
GET/tenants/:tenantId/domains…
listDomains / addDomain / verifyDomain / deleteDomain
Custom domains.
POST/tenants/:tenantId/telegram/bot…
registerBot / botClaimLink / reconfigureBot / deleteBot
Telegram bot.
GET…/telegram/bots/:botId/shops…
listBotShops / bindBotToShop / setBotShopDefault / unbindBotFromShop
Bot ↔ shop.
GET/tenants/:tenantRef/shops…
listShops / createShop / getShop / updateShop / deleteShop
Shops under an org.
GET/tenants/:tenantRef/storefronts…
listStorefronts / createStorefront / getStorefront / updateStorefront / deleteStorefront
Storefronts.
GET…/storefronts/:storefrontId/shops…
listStorefrontBindings / bindShopToStorefront / updateStorefrontBinding / unbindShopFromStorefront
Bind shops to a storefront.
GET…/verticals, …/shops/:shopId/vertical-version
listVerticals / getShopVerticalVersion / upgradeShopVertical
Vertical packs.
GETGET …/finance/shop-revenue
shopRevenue(ref, shopId?)
Shop ledger totals.
Customers, Collections & Reviews
15 methods
METHOD
DOES
ROUTE
listCustomers(query?) / importCustomers(rows)
Customer CRM.
GET/marketplace/seller/customers…
getCustomerTags / addCustomerTag / removeCustomerTag
Customer tags.
GET…/customers/:buyerId/tags…
listCollections / createCollection / getCollection / updateCollection / deleteCollection
Collections.
GET/collections…
addToCollection(colId, tplId) / removeFromCollection(colId, tplId)
Collection membership.
POST…/collections/:id/templates…
listReviews(subjectType, subjectId) / reviewSummary(subjectType, subjectId)
Read reviews.
GET/marketplace/reviews/:subjectType/:subjectId…
replyToReview(reviewId, body)
Reply to a review.
POSTPOST …/reviews/:id/reply
GET/marketplace/seller/customers…
listCustomers(query?) / importCustomers(rows)
Customer CRM.
GET…/customers/:buyerId/tags…
getCustomerTags / addCustomerTag / removeCustomerTag
Customer tags.
GET/collections…
listCollections / createCollection / getCollection / updateCollection / deleteCollection
Collections.
POST…/collections/:id/templates…
addToCollection(colId, tplId) / removeFromCollection(colId, tplId)
Collection membership.
GET/marketplace/reviews/:subjectType/:subjectId…
listReviews(subjectType, subjectId) / reviewSummary(subjectType, subjectId)
Read reviews.
POSTPOST …/reviews/:id/reply
replyToReview(reviewId, body)
Reply to a review.
Media library
8 methods
METHOD
DOES
ROUTE
listFiles(query?) / fileFacets() / getFile(id)
Browse the library.
GET/files…
uploadFile(form) / uploadProductImages(form) / uploadAvatar(form)
Upload (pass a FormData).
POSTPOST /files/upload…
addFileFromUrl({url})
Server-side fetch (SSRF-guarded).
POSTPOST /files/from-url
bulkDeleteFiles(ids)
Delete many.
POSTPOST /files/bulk-delete
GET/files…
listFiles(query?) / fileFacets() / getFile(id)
Browse the library.
POSTPOST /files/upload…
uploadFile(form) / uploadProductImages(form) / uploadAvatar(form)
Upload (pass a FormData).
POSTPOST /files/from-url
addFileFromUrl({url})
Server-side fetch (SSRF-guarded).
POSTPOST /files/bulk-delete
bulkDeleteFiles(ids)
Delete many.
Finance / Earnings
6 methods
METHOD
DOES
ROUTE
wallet(shopId?)
Escrow wallet, bucketed per shop.
GETGET /payment/wallet
listPayments(query?) / getPayment(id)
Payments.
GET/payment…
paymentStats() / paymentHistory(query?) / exportPayments(query?)
Reporting.
GET/payment/stats|history|export
GETGET /payment/wallet
wallet(shopId?)
Escrow wallet, bucketed per shop.
GET/payment…
listPayments(query?) / getPayment(id)
Payments.
GET/payment/stats|history|export
paymentStats() / paymentHistory(query?) / exportPayments(query?)
Reporting.
Disputes, Chat & Notifications
18 methods
METHOD
DOES
ROUTE
listDisputes / getDispute / openDispute / addDisputeEvidence / disputeStatistics
Disputes as a party.
GET/disputes…
listChats(query?) / openRequestChat(requestId) / openSupportChat()
Conversations.
GET/chat…
getMessages / sendMessage / markChatRead / archiveChat / chatUnreadCount
Messaging.
GET/chat/:id/messages…
listNotifications / notificationsUnreadCount / notificationSettings / markNotificationRead / markAllNotificationsRead
Notifications.
GET/notifications…
GET/disputes…
listDisputes / getDispute / openDispute / addDisputeEvidence / disputeStatistics
Disputes as a party.
GET/chat…
listChats(query?) / openRequestChat(requestId) / openSupportChat()
Conversations.
GET/chat/:id/messages…
getMessages / sendMessage / markChatRead / archiveChat / chatUnreadCount
Messaging.
GET/notifications…
listNotifications / notificationsUnreadCount / notificationSettings / markNotificationRead / markAllNotificationsRead
Notifications.
BUYER API — the escrow lifecycle, top to bottom
The buyer namespace is one lifecycle, top to bottom. Every method below moves an order along this chain — and exactly one step is irreversible. This is the happy path; an order can also leave it as cancelled, disputed, refunded or payment_failed.
ESCROW STATUS CHAIN
pending_payment
pending
active
received_offers
in_negotiation
payment
processing
delivery
delivered
confirming
seller_paid
completed
buyer or seller action
money moves (into escrow, or out to the seller)
irreversible — escrow released
Irreversible —
confirmDelivery() is the confirming → seller_paid transition. It releases escrow to the seller and cannot be undone. Everything before it can still be disputed.Discovery
Find sellers and browse published products.
2 methods
Requests & Offers
Open a request, read offers, accept one.
6 methods
Negotiation
Counter, message, and agree on terms.
3 methods
Payment (escrow / on-chain via AMN scanner)
Create the intent; funds are held, not sent.
4 methods
Take delivery & after-sale
Reveal goods, confirm delivery, or dispute.
8 methods
Discovery
2 methods
METHOD
DOES
ROUTE
listSellers(query?)
Browse shops.
GETGET /marketplace/sellers
sellerCatalog(sellerId)
One shop's templates.
GETGET …/request-templates/sellers/:sellerId
GETGET /marketplace/sellers
listSellers(query?)
Browse shops.
GETGET …/request-templates/sellers/:sellerId
sellerCatalog(sellerId)
One shop's templates.
Requests & Offers
6 methods
METHOD
DOES
ROUTE
createRequest(input)
Open a purchase request. Omit sellerId to broadcast.
POSTPOST …/purchase-requests
buyProduct(input)
Buy a catalog product by templateId (thin alias over create).
POSTPOST …/purchase-requests
myRequests(query?)
The buyer's own requests.
GETGET …/purchase-requests/my
getRequest(id)
One request.
GETGET …/purchase-requests/:id
listOffers(requestId)
Offers received.
GETGET …/purchase-requests/:id/offers
selectOffer(requestId, offerId)
Accept an offer — the gate before payment.
POSTPOST …/purchase-requests/:requestId/select-offer
POSTPOST …/purchase-requests
createRequest(input)
Open a purchase request. Omit sellerId to broadcast.
POSTPOST …/purchase-requests
buyProduct(input)
Buy a catalog product by templateId (thin alias over create).
GETGET …/purchase-requests/my
myRequests(query?)
The buyer's own requests.
GETGET …/purchase-requests/:id
getRequest(id)
One request.
GETGET …/purchase-requests/:id/offers
listOffers(requestId)
Offers received.
POSTPOST …/purchase-requests/:requestId/select-offer
selectOffer(requestId, offerId)
Accept an offer — the gate before payment.
Negotiation
3 methods
METHOD
DOES
ROUTE
negotiate(offerId, {price?, note?})
Start/append a negotiation thread.
POSTPOST …/offers/:offerId/negotiations
counterOffer(offerId, price, note?)
Counter.
POSTPOST …/offers/:offerId/negotiations/counter
acceptNegotiation(offerId)
Accept.
POSTPOST …/offers/:offerId/negotiations/accept
POSTPOST …/offers/:offerId/negotiations
negotiate(offerId, {price?, note?})
Start/append a negotiation thread.
POSTPOST …/offers/:offerId/negotiations/counter
counterOffer(offerId, price, note?)
Counter.
POSTPOST …/offers/:offerId/negotiations/accept
acceptNegotiation(offerId)
Accept.
Payment (escrow / on-chain via AMN scanner)
4 methods
METHOD
DOES
ROUTE
paymentOptions()
Chain/token options.
GETGET /payment/amn-scanner/options
createPaymentIntent(input)
Create an escrow payment intent.
POSTPOST /payment/amn-scanner/intents
getCheckout(intentId)
Checkout block for the wallet/UI.
GETGET /payment/amn-scanner/:id/checkout
verifyPayment({txHash})
Verify a tx against records.
POSTPOST /payment/verify
GETGET /payment/amn-scanner/options
paymentOptions()
Chain/token options.
POSTPOST /payment/amn-scanner/intents
createPaymentIntent(input)
Create an escrow payment intent.
GETGET /payment/amn-scanner/:id/checkout
getCheckout(intentId)
Checkout block for the wallet/UI.
POSTPOST /payment/verify
verifyPayment({txHash})
Verify a tx against records.
Take delivery & after-sale
8 methods
METHOD
DOES
ROUTE
confirmDelivery(requestId)
Irreversible — releases escrow to the seller.
POSTPOST …/purchase-requests/:id/final-confirm
revealDigital(requestId)
Reveal/receive a delivered digital good.
POSTPOST /digital-goods/orders/:requestId/reveal
myDeliveries()
The buyer's digital vault.
GETGET /digital-goods/my-deliveries
myOrders(query?)
Orders across all shops.
GETGET /orders/mine
leaveReview(input)
Leave a review.
POSTPOST /marketplace/reviews
openDispute(input)
Open a dispute — escrow stays held.
POSTPOST /disputes
openChat(requestId)
Open chat tied to a request.
POSTPOST /chat/purchase-request
sendMessage(chatId, text)
Send a chat message.
POSTPOST /chat/:id/messages
POSTPOST …/purchase-requests/:id/final-confirm
confirmDelivery(requestId)
irreversibleIrreversible — releases escrow to the seller.
POSTPOST /digital-goods/orders/:requestId/reveal
revealDigital(requestId)
Reveal/receive a delivered digital good.
GETGET /digital-goods/my-deliveries
myDeliveries()
The buyer's digital vault.
GETGET /orders/mine
myOrders(query?)
Orders across all shops.
POSTPOST /marketplace/reviews
leaveReview(input)
Leave a review.
POSTPOST /disputes
openDispute(input)
Open a dispute — escrow stays held.
POSTPOST /chat/purchase-request
openChat(requestId)
Open chat tied to a request.
POSTPOST /chat/:id/messages
sendMessage(chatId, text)
Send a chat message.
Irreversible — confirmDelivery() releases escrow to the seller. Only after the buyer inspected the goods — gate it behind a human approve.
Tool catalog
Every tool
agentTools(scope) returns, grouped by scope and searchable — because thirty-eight cards on one grid is a wall. Dispatch one tool_use block with runTool(client, call).showing 28 of 38
3 tools are irreversible —
seller_deliver_digital, seller_delete_product and buyer_confirm_delivery release goods, release escrow or delete data. Gate each one behind a human approve in any UI.SELLER TOOLS
28 tools
seller_list_products
List the shop's own products (کالا). Use before editing to get ids.
seller_item_schema
Return the vertical pack's product fields. Call before adding a product.
seller_add_product
Add a product (کالا) to the shop catalog.
seller_update_product
Edit an existing product; pass only the fields to change.
seller_toggle_product
Publish or unpublish a product.
seller_add_stock
Add digital inventory (codes/keys) that orders draw from.
seller_list_orders
The seller's sales ledger (own line items).
seller_make_offer
Make an offer on a buyer's open purchase request.
seller_confirm_agreement
Countersign the pre-payment summary so the buyer can pay.
seller_deliver_digital
irreversibleDeliver a digital good to a paid order.
seller_get_shop_settings
Read the current shop settings.
seller_update_shop_settings
Update shop settings (name, logo, cover, policies…).
seller_get_product
Read one product (کالا) by id — price, status, vertical fields.
seller_delete_product
irreversibleDelete a product from the shop. Irreversible.
seller_list_inventory
List the digital inventory (codes/keys) the shop holds.
seller_get_order
Read one order (sale) by id.
seller_browse_requests
Browse buyers' open requests the shop could offer on.
seller_my_offers
List the shop's own offers across requests, with status.
seller_counter_offer
Counter a buyer's negotiation with a new price.
seller_set_delivery
Set delivery info on an order for a non-digital good.
seller_generate_delivery_code
Generate a hand-off delivery code the buyer verifies on receipt.
seller_wallet
Read the shop's escrow wallet / earnings, optionally per shop.
seller_list_customers
List the shop's customers.
seller_reply_review
Post the shop reply to a customer review.
seller_list_chats
List the shop conversations with buyers.
seller_send_message
Send a chat message to a buyer in an existing conversation.
seller_list_notifications
List seller notifications (new offers, payments, disputes…).
seller_open_dispute
Open a dispute on an order as the seller — escrow stays held.