---
title: "Nook docs: agent quickstart"
description: "How an agent integrates Nook v3: register a partner key, connect a buyer's stores with one link, get a real checkout quote, and buy with the buyer's approval."
canonical: https://nookstore.xyz/docs
last_updated: 2026-11-05
---

# Nook quickstart for agents

This is the short version. The full, canonical guide is [Nook for agents (v3)](https://nookstore.xyz/agents.md), and machine-readable discovery is at [nookstore.xyz/.well-known/nook.json](https://nookstore.xyz/.well-known/nook.json). Base URL for every call: `https://nookstore.xyz`, with `Authorization: Bearer <your partner key>`.

Prefer tools? An MCP client can add `https://nookstore.xyz/mcp` (Streamable HTTP) with the header `Authorization: Bearer <your partner key>`; the tools take the same bodies as the API and follow the same rules.

## 0. Get a partner key

Skip this if your developer gave you one. Otherwise register your own — it works at once:

1. Make the key yourself: `nk_` plus 32 random bytes in base64url (43 characters), and save it in your host's private storage. Nook stores only its hash and can never show it again.
2. `POST /v3/api/agent/register` with that key as the Bearer token and `{ "id": "<your agent id>", "name": "<what the buyer sees>", "host": "<the product you run in>" }`.
3. `GET /v3/api/agent/me` confirms who Nook has you as, the connections buyers granted you, and your counts.

Never show the key to the buyer or ask them for one.

## 1. Connect the buyer's stores

`POST /v3/api/agent/connect-links` with `{ "merchants": "all" }` returns one `url` that works for 30 minutes. Send the buyer that link. They sign in to Nook with their phone, see their connected accounts, and connect every signed-in one to you with one tap. You never see what they type.

Stores: Amazon, Uber Eats, Instacart, Walmart, Target and Chewy can quote and buy. DoorDash, Urban Outfitters, Resy, Detoure, Delta and Apple connect only for now. [What each store supports](/stores).

## 2. Get a quote

`POST /v3/api/agent/quotes` with the buyer's `connection_id` and what they asked for. Nook works through their signed-in account, finds the product, reads the store's own checkout figures, and puts the cart back. Poll the quote until it is ready, then show the buyer the item and the total.

## 3. Buy with the buyer's approval

Show the quote's item and total and ask. Any clear affirmative reply to that total, in the buyer's own words, is their approval: `POST /v3/api/agent/purchases` with their words as the confirmation. Without their words, they approve on Nook's signed-in review page instead. A higher total — or another item, address or card — stops the purchase. Nook presses the store's final order button once and checks for confirmation.

## 4. Check state

`GET /v3/api/agent/me` for your connections and counts; poll the purchase until it settles, then tell the buyer the order number. Never retry an uncertain order.

## Next steps

- [Full agent guide](https://nookstore.xyz/agents.md): errors, preferences, polling and recovery
- [Your accounts](https://nookstore.xyz/v3/accounts): where buyers connect and manage stores
- [Pricing](/pricing) · [FAQ](/faq) · [Contact](/contact)
- [llms.txt](/llms.txt): a short index of this site for AI agents