For AI agents
A marketplace your agent can buy from.
One anonymous API call registers an agent. From there it can search listings, place escrow-protected orders, pay in Nano (XNO) from its own wallet, and pull KMS-signed receipts. No account, no card rails, no custodian.
Bring your own Nano wallet. Nagora is the exchange layer: your agent controls its own keys and funds every escrow directly on-chain.
Three calls to a first purchase.
Register in one call
POST a name and a refund Nano address to /agents/v1/register. No account, no signup: the API key comes back in the same response.Spend within caps
Self-registered keys can spend 25 XNO per transaction and 100 XNO a day, enforced server-side. Manage the agent from an account to raise them.Search, order, fund
Search listings anonymously. POST a purchase, get a per-order escrow deposit address, send Nano from your own wallet.
Three ways in: hosted MCP, local MCP, or raw HTTP
The hosted MCP endpoint is the fastest path: one command, nothing installed. The npm package runs the same tools locally and stores the key for you. Everything is plain HTTP underneath, so any runtime can use curl instead.
# Hosted server: nothing to install, no key, no account
claude mcp add --transport http nagora https://api.nagora.shop/mcp
# Once register_agent has returned your key, pin it for future
# sessions so every tool authenticates automatically:
claude mcp add --transport http nagora https://api.nagora.shop/mcp \
--header "Authorization: Bearer nag_agt_..."The hosted server has no local storage, so register_agent returns the key once in its result. Your agent can keep buying in the same session by passing it as the apiKey argument on each tool; pin it as an Authorization header (above) for future sessions. A typical first run:
You: Find a mechanical keyboard under 50 XNO and buy it.
Claude: [search_listings q="mechanical keyboard" maxPrice=50]
[register_agent name="claude-shopper"
nanoAddress="nano_1yourwallet..."] <- one-time, no account needed
[create_purchase listingId="..." quantity=1 shippingAddress={...}]
Order placed. Fund escrow by sending exactly 23.4 XNO to
nano_3escrowaddr... and I will watch the order from there.
[get_order ...] -> escrowStatus: "Funded", then "Shipped"
[confirm_delivery ...] once it arrives -> funds release to the seller
[get_receipt ...] -> cryptographically signed proof of the tradeAuth, in one sentence
Search and listing detail are anonymous; everything that touches an order sends Authorization: Bearer nag_agt_.... Keys are stateless, revocable, and verified against a KMS-held HMAC: the plaintext is never stored server-side.
What happens between paying and getting paid
Every order is wrapped in an on-chain escrow with a small state machine and three safety timers. This is the whole thing; there are no hidden states.
Initiated
Order: PendingYour agentPOST /agents/v1/purchases creates the order, reserves stock, and issues a fresh per-order Nano account as the escrow deposit address. Nothing has been paid yet; you can still cancel.
TimerUnfunded orders auto-cancel after 60 minutes and the stock goes back on sale.
Funded
Order: AwaitingShipmentAutomaticYou send exactly amountNano to the deposit address from your own wallet. Nagora watches the chain and promotes the escrow the moment the funds land. No API call needed.
TimerIf the seller never ships, the escrow auto-cancels after 7 days and refunds your nanoAddress in full.
Shipped
Order: ShippedSellerThe seller marks the order shipped and attaches tracking. You will see it on GET /orders/{id} and receive an order.shipped webhook if you registered a callbackUrl.
TimerIf you never confirm, escrow auto-finalises to the seller after 14 days.
Delivered, then Released
Order: CompletedYour agentPOST /orders/{id}/confirm once the goods or digital content arrive. Escrow pays the seller on-chain (minus the platform fee; orders of $2 and under are fee-free), and a cryptographically signed receipt is generated.
The three exits that are not a sale
- Cancelled
- Unfunded orders only: POST /orders/{id}/cancel, or the 24-hour timer. Stock is restored, nothing was ever paid.
- Refunded
- Funded but never shipped, or a dispute resolved in the buyer's favour: the full escrow amount returns on-chain to the agent's registered nanoAddress.
- Disputed
- Open from the website while escrow is Funded, Shipped, or Delivered. A human reviews within 24 hours and all timers pause. Self-registered agents do not have an API dispute path yet: contact support.
Stop polling: get signed events
Register a callbackUrl (at registration or later via PATCH) and Nagora POSTs every order state change to it. A webhookSecret is generated the first time a URL is set; fetch it any time from GET /agents/v1/me.
| Event | Fires when |
|---|---|
order.funded | Your deposit was detected on-chain; escrow now holds the funds |
order.shipped | Seller marked the order shipped (or a digital order auto-shipped); tracking available. This is your cue to verify delivery and confirm. |
Every delivery carries X-Nagora-Timestamp and X-Nagora-Signature headers. Verify with a constant-time HMAC comparison before trusting the payload:
// Verify an incoming Nagora webhook (Node)
import crypto from "node:crypto";
function verifyNagoraWebhook(rawBody, headers, webhookSecret) {
const timestamp = headers["x-nagora-timestamp"];
const signature = headers["x-nagora-signature"]; // "sha256=<hex>"
const expected = crypto
.createHmac("sha256", webhookSecret)
.update(`${timestamp}.${rawBody}`)
.digest("hex");
return crypto.timingSafeEqual(
Buffer.from(signature.slice("sha256=".length), "hex"),
Buffer.from(expected, "hex"),
);
}These two events cover the waits an agent actually has (payment detection and fulfilment); terminal states follow your own confirm call. Treat GET /agents/v1/orders/{id} as the source of truth and the webhook as the wake-up call.
Designed so a runaway agent cannot hurt you
The API assumes the buyer is a language model that might misread a price, loop, or get prompt-injected. Every layer below is enforced server-side; none of it relies on the agent behaving.
- Escrow by default
- Funds never go straight to a seller. They sit in a per-order on-chain account until delivery is confirmed, with automatic refund paths if it never is.
- Server-side spending caps
- Per-transaction and rolling per-day XNO limits on every key. A confused agent gets a 400, not an empty wallet. Pending orders count toward the daily cap to block parallel-burst abuse.
- Keyless server, revocable client
- Nagora never holds your wallet keys and never stores key plaintext (KMS-HMAC verification). Revoke any key and it stops working within 60 seconds.
- Price-drift protection
- Pass quotedTotalNano from the listing you showed the user and the purchase fails if the FX rate moved more than 2% since. The agent buys what it said it would buy.
Proof a trade happened, independent of Nagora
When escrow releases, Nagora canonicalises the order facts, hashes them, and signs the hash with an AWS KMS ECDSA key. Where possible the seller co-signs with the Ed25519 key behind their own Nano address.
{
"receiptId": "9f2c...",
"orderId": "b81a...",
"issuedAt": "2026-06-11T14:02:11Z",
"sellerHandle": "vintagewatchco",
"sellerNanoAddress": "nano_1seller...",
"listingTitle": "Seiko 5 automatic, 1996",
"totalXno": 23.4,
"escrowDepositAddress": "nano_3escrow...",
"sellerPayoutBlockHash": "A1B2C3...", // verifiable on any Nano explorer
"nagoraKeyId": "arn:aws:kms:...",
"nagoraSigAlgorithm": "ECDSA_SHA_256",
"nagoraSignature": "MEUCIQ...", // Nagora signs the canonical payload
"sellerSignature": "5a3f..." // seller's own Ed25519 key, when available
}Verifying one
- Recompute SHA-256 over the canonical payload and compare to the stored hash.
- Verify nagoraSignature against Nagora's published KMS public key.
- Verify sellerSignature (Ed25519) against the seller's Nano address, when present.
- Look up sellerPayoutBlockHash on any Nano explorer: the payout itself is public, immutable, and exactly matches the receipt amount.
Receipts are also rendered human-readable at nagora.shop/receipt/<id>.
The numbers your retry logic should know
- Spending caps (self-registered)
- 25 XNO per transaction, 100 XNO per rolling day. Enforced per key, server-side. Raise them by managing the agent from a Nagora account.
- Unfunded orders
- At most 10 orders awaiting payment per agent. Fund or cancel before placing more.
- Purchase rate
- 30 purchases per minute per agent.
- Registration
- Strictly rate-limited per IP. Register once and persist the key; do not register per purchase run.
- FX drift guard
- Pass quotedTotalNano from a recent listing read and the order is rejected if the live total drifts more than 2%. Omit it to skip the check.
- 429 responses
- Include a Retry-After header in seconds. Back off and retry; do not hammer.
- Key revocation
- Revoked keys stop authenticating within 60 seconds.
The questions agents (and their humans) ask
Do I need a Nagora account?
Where does the money actually sit?
What happens if the seller never ships?
What if my agent loses its API key?
Why Nano and not a card or a stablecoin?
Can humans use these rails too?
OpenAPI 3.1 spec, publicly readable
All agent-facing endpoints, schemas, and auth definitions. Import it into Postman or Bruno, generate an SDK, or hand the URL straight to your agent's tool-use planner.
Ready to build?
Your agent's first purchase is one register call and one Nano block away. Accounts are optional; escrow is not.