Going Live

Going live is one approval. The agent asks for a key, a human clicks Allow in a browser, and the agent picks up a zn_live_ key on its next poll — along with the wallet balance and a $5 starter credit big enough to pay for one real order. Nothing the agent built is lost: the sandbox it was working against folds into the approving account, and the sandbox key keeps working for test mode.

Agents: install the universal-checkout skill — npx skills add zincio/skills --skill universal-checkout — and follow its Getting started section, which carries these calls step by step. This page explains the flow to the person who has to click Allow.

The approval flow

The agent asks for a key

curl -X POST https://api.zinc.com/device/code \
  -H "Authorization: Bearer $ZINC_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "acme-restock-agent"}'

The sandbox key as a Bearer token is optional, but sending it attaches the sandbox: approval then claims its orders and its key onto the account, and it’s what makes the starter credit available.

{
  "device_code": "…",
  "user_code": "XXXX-XXXX",
  "verification_uri": "https://app.zinc.com/activate",
  "verification_uri_complete": "https://app.zinc.com/activate?code=XXXX-XXXX",
  "expires_in": 900,
  "interval": 5,
  "human_message": "Open https://app.zinc.com/activate?code=XXXX-XXXX and click Allow …",
  "next": "…"
}

human_message is written to be shown to a person as-is. device_code is the agent’s half of the handshake and should never be shown to anyone.

The human approves it

They open verification_uri_complete in any browser — their laptop, their phone, a machine the agent has never touched — and sign in with Google, GitHub, or an email magic link.

The magic link brings them back to the approval even if they open it in a different browser than the one they started in, so the link can be forwarded or read on a phone.

The page names the agent, says whether a sandbox is attached and whether a starter credit is on the table, and offers Allow or Deny. Clicking Allow issues the key.

The agent polls for the key

curl -X POST https://api.zinc.com/device/token \
  -H "Content-Type: application/json" \
  -d '{"device_code": "…"}'

Poll every interval seconds (5). While waiting, the response is an RFC 8628–shaped error:

Status	Code	What it means
400	`authorization_pending`	Nobody has decided yet. Keep polling.
400	`slow_down`	You’re polling faster than `interval`. Back off.
400	`expired_token`	15 minutes elapsed, or the key was already collected. Start a new code.
403	`access_denied`	The human clicked Deny. Stop; don’t start another code.

The key is returned exactly once. A second successful poll gets expired_token, so persist the key the moment it arrives.

Success

{
  "api_key": "zn_live_...",
  "name": "acme-restock-agent",
  "is_test": false,
  "wallet_balance_cents": 500,
  "sandbox": {
    "orders_moved": 3,
    "keys_moved": 1,
    "note": "Your sandbox order history and its key now belong to this account. …"
  },
  "starter_credit": {
    "cents": 500,
    "reason": "granted",
    "wallet_balance_cents": 500,
    "max_price_cents": 400,
    "message": "…",
    "picks": [ … ]
  }
}

The key is under api_key — the same field name the sandbox mint used. sandbox is absent when no sandbox key was attached.

The starter credit

The first time an account approves an agent whose attached sandbox actually placed an order, $5 is added to the wallet. Once per account, not once per agent. The starter_credit object is on every key-issuing response whether or not a credit landed, so an agent never has to infer its budget:

Field
`cents`	What this approval added. `0` when nothing was added.
`reason`	`granted`, `already_granted` (this account already had its one credit), or `no_sandbox_order` (no proven sandbox was attached).
`wallet_balance_cents`	Spendable balance right now.
`max_price_cents`	The largest `max_price` an order can carry on the wallet alone — the balance minus the $1 per-order fee.
`message`	The same thing in a sentence, for showing to a person.
`picks`	Concrete items that fit the budget, with orderable URLs.

5 buys less than it looks like: every order carries a

1 fee, so the item plus tax and shipping has to come in under $4. That’s what max_price_cents is — use it, don’t recompute it.

Today’s picks are a Mainstays Darby 16 oz stoneware mug (

2.88) and Lipton black tea bags, 24 count (

3.42), both on walmart.com. They’re chosen to land under the budget delivered, so the first real order is a formality rather than a research project. The account also gets the usual default Production and Test API keys created at first sign-in. The agent’s key is separate from both and named after the agent, so the human can see which key belongs to which agent — and revoke just that one — in Settings.

Your first live order

Find something in budget

GET /search takes the same price ceiling your order will:

curl "https://api.zinc.com/search?q=stoneware+mug&max_price=400" \
  -H "Authorization: Bearer $ZINC_LIVE_KEY"

max_price and min_price are in cents — the same number you’ll send as max_price on POST /orders, so every result you get back fits the order you intend to place. Results priced above the ceiling are dropped, and so are results whose price isn’t known: a filter that lets through “price unknown” isn’t a filter.The response carries excluded_by_price (how many orderable results the clamp removed) and, when the clamp emptied the list entirely, a hint saying so. Each result’s url is what you pass to POST /orders.

Search is metered against the wallet, so on a $5 balance it’s worth searching once with a good query rather than fanning out over variations. Or skip it: starter_credit.picks already carries orderable URLs.

Place it

curl -X POST https://api.zinc.com/orders \
  -H "Authorization: Bearer $ZINC_LIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "products": [{"url": "https://www.walmart.com/ip/…", "quantity": 1}],
    "shipping_address": {
      "first_name": "…", "last_name": "…",
      "address_line1": "…", "city": "…",
      "state": "CA", "postal_code": "94105",
      "phone_number": "4155552671", "country": "US"
    },
    "max_price": 400
  }'

Set max_price at or under starter_credit.max_price_cents. The full shipping_address is required, including phone_number — retailers reject orders without one. Phone numbers come back normalized to E.164 (+14155552671).

Wait — for real this time

curl https://api.zinc.com/orders/<order_id> \
  -H "Authorization: Bearer $ZINC_LIVE_KEY"

A live order sits at pending for minutes while a worker actually places it at the retailer — unlike the sandbox, where it advances in a second. Poll GET /orders/{id}, or register a webhook. order_placed is the success terminal for the order itself; shipping progress then shows up under tracking_numbers[].

When the wallet runs out

POST /orders refuses with 402 and the code insufficient_funds. The numbers and the way forward are in error.details:

{
  "error": {
    "code": "insufficient_funds",
    "message": "Insufficient wallet balance. Required: $12.99, Available: $4.00",
    "details": {
      "required": 1299,
      "available": 400,
      "short_by": 899,
      "fund_with": [ … ]
    }
  }
}

fund_with lists three rails, in order of least human involvement:

`rail`	Who pays	How
`agent_wallet`	The agent, from its own USDC	`POST /agent/orders` with the same body and no `Authorization` header. The 402 challenge lists MPP (Tempo) and x402 (USDC on Base) — pay and retry. No Zinc wallet involved. See MPP.
`human_card`	The operator’s card, approved per order	With Stripe’s Link CLI installed and signed in, create a spend request for the order amount, have the operator approve the push, then pay `POST /agent/orders?method=stripe` with the resulting credential.
`human_topup`	The operator, by funding the wallet	They add funds in the dashboard under Wallet; the balance updates when the payment settles. Then retry. See Wallet.

On the human_card rail, the spend request must be for the 402 challenge amount — max_price plus the $1 order fee — not the item price. A request for less is declined at capture.

Check the balance any time with GET /wallet/me.

Claiming without a device code

The claim_url from the mint response still works as an alternative human step. Hand it over:

“I’ve built and tested the ordering flow against a Zinc sandbox. To adopt it into your account, sign in here: https://app.zinc.com/claim/...”

Signing in there folds the sandbox — order history and key — into their Zinc account, and the sandbox key keeps working. What it doesn’t do is give the agent a live key: claiming moves ownership, not the ability to spend. Use it when the human wants to adopt the work now and decide about live access later. An agent that handed over a URL can’t see what happened next, so poll:

curl https://api.zinc.com/sandbox/status \
  -H "Authorization: Bearer $ZINC_KEY"

`claimed`	Meaning
`false`	Still provisional — nobody has claimed it. Keep waiting, or re-send the URL.
`true`	Claimed. `claimed_by_email` names the account it now belongs to.

The claim token is single-use and lives only in that URL. Only its hash is stored, so it can’t be reproduced — if it’s lost, use the device flow above instead.

Seeing the account’s keys

GET /api-keys called with an API key returns the caller’s own key in full and every other key masked to its prefix and last four characters (zn_live_…ab12) — enough to recognise a key in a list, useless as a credential. A human signed into the dashboard sees full keys there.

A key that could read its siblings’ secrets could become any of them. The device flow hands keys to agents an account owner has only just met, so that door is closed.

What changes when you switch

The request and response shapes don’t change. The environment around them does:

	Sandbox	Live
Money	Nothing is charged	Every order draws from a wallet, plus a $1 order fee
Balance checks	Skipped	Enforced — an underfunded order gets a 402
URL reachability	Skipped	Enforced
Address verification	Skipped	Enforced against external validation
Retailer URL validation	Skipped	Enforced
Timing	Fast clock — seconds	Real — placement takes minutes, delivery takes days
Failures	Only the ones you asked for	Whatever the retailer does

Because the sandbox skips those validations, your first live order can fail in ways no test did — a rejected address, an unreachable URL, a real out-of-stock. Handle order_failed and the synchronous rejections before you switch, not after.

Before your first live order

Handle both failure timings. Some errors come back from POST /orders; others arrive minutes later as order_failed. See Error Handling.
Set max_price to cover the real total. Item plus tax plus shipping — a ceiling that only covers the item price trips max_price_exceeded on live orders that would have passed in the sandbox.
Re-register webhooks. Test-mode webhook config is separate from live; a live key won’t inherit it.
Send an idempotency key. On live orders, a retry without one is a second order. See Idempotency.
Start small. One cheap real order end to end before you turn on volume — which is exactly what the starter credit is for.

Reference

Wallet

Balances, funding, and the order fee schedule.

Get Sandbox Status

GET /sandbox/status — every response shape.

Getting Started

MCP Server

Agent Sandbox

Agent Skills

Ways to Pay

Migrating from V1

FAQ

The approval flow

The starter credit

Your first live order

When the wallet runs out

Claiming without a device code

Seeing the account’s keys

What changes when you switch

Before your first live order

Reference

Wallet

Get Sandbox Status

​The approval flow

​The starter credit

​Your first live order

​When the wallet runs out

​Claiming without a device code

​Seeing the account’s keys

​What changes when you switch

​Before your first live order

​Reference

Wallet

Get Sandbox Status

The approval flow

The starter credit

Your first live order

When the wallet runs out

Claiming without a device code

Seeing the account’s keys

What changes when you switch

Before your first live order

Reference