A
AMN
/ sdk
v0.1.1
Back to home
GETTING STARTED
CORE
SELLER API
BUYER API
AGENTS
@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.
.seller
The complete shop surface — catalog, inventory, offers, orders, settings, finance, disputes (~90 operations).
.buyer
Discovery, 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>"
  }
}
status
number — HTTP status.
path
string — The route that failed.
body
unknown — Parsed error payload.
message
string — 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)
irreversible
Releases 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)
irreversible
Rotates 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)
irreversible
Irreversible — 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
irreversible
Deliver 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
irreversible
Delete 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.
ON THIS PAGE