Buyer account tools
These tools are the agent’s window into the signed-in buyer’s own account: profile, addresses, order/return history, wallet balance, coupons, and gifts. They are strictly scoped to the buyer resolved from the bearer.
Buyer OAuth bearer only. Never attach the platform
X-API-Keyto these calls — the API prefers the key and the buyer would never be resolved (see Authentication). On Path A the bridge dynamically discovers these tools from/account/mcpand proxies them, so new account tools appear without a bridge release.
Recommended first call
Call get_buyer_context before shopping so you can ship to the default address
and respect spend caps without asking.
{ "name": "get_buyer_context", "arguments": {} }Returns the buyer profile (id, email, name, phone, suiAddress),
defaultAddress, otherAddressLabels, hasAgentAuthorization, and
spendingCaps (maxPerOrderAmount, dailyCapAmount, spentTodayAmount,
currency, expiresAt) when an agent authorization exists.
The full tool set
| Tool | Input | Returns |
|---|---|---|
get_buyer_context | — | Profile, default address, other address labels, spend caps |
list_my_addresses | — | Saved shipping/billing address book (cross-store) |
list_my_orders | — | Order history across every store |
get_my_order | order_id | Full order detail (items, totals, address, tracking) |
list_my_returns | — | Return requests (RMAs) with refund status |
get_wallet_balances | — | On-chain balances valued in USD (USDsui, SUI, …) |
list_my_coupons | — | Spendable Artos coupons (balance, min subtotal, expiry) |
list_my_gifts | — | Artos Cash gifts sent and received |
claim_gift | gift_id | Claims an awaiting_claim gift into a redeemable coupon |
Coupons and gifts
- Coupons are spendable store credit usable at any Artos store. They redeem automatically when the buyer pays with crypto, apply up to the full order total, and are reusable; only one applies per order (no stacking). See Checkout → Coupons.
- Gifts with status
awaiting_claimmust be claimed (requires a linked wallet) before they can be spent; once claimed a gift becomes a normal coupon.
Money formatting
Buyer-account responses are formatted for agents — monetary values are rendered as
currency strings rather than raw minor units, so an agent reports a $3.00 gift
correctly instead of seeing 300.