Overview

BridgesAgents brings together products, prices and stock from stores in any retail segment (grocery, electronics, pharmacy, fashion...) in a format ready for AI shopping agents.

There are three ways to query the catalog, all with the same agent key:

• MCP, for AI agents (Claude, ChatGPT, your own agents): the agent discovers and calls the tools on its own.
• REST API, for traditional systems and integrations.
• UCP (Universal Commerce Protocol), for agents that already speak that standard.

Start here: create a developer account, generate an agent key under Agent keys in the dashboard and send it with every request in the Authorization: Bearer abd_… header (details in Authentication).

Concepts

Details the agent should take into account:

• effectivePrice is the price to pay: the promotional price when there is one, otherwise the regular price.
• updatedAt tells when price and stock were last updated. stale: true flags an offer not updated for more than 7 days (the price may have changed); after 30 days it no longer shows up for agents.
• soldByWeight means the item is sold by weight (e.g. fresh produce): the price is per kg and the final amount is only known when the order is picked.
• Units (unit): UN (each), KG, G, L, ML.
• requiresPrescription: a medicine that requires a prescription. The agent must not complete the purchase; tell the consumer to present the prescription at the pharmacy.
• adult: true: 18+ product (alcoholic beverages, tobacco). BridgesAgents only flags it; the agent is the one who checks the age.
• inStoreOnly: true: sold on site only (fuel). It can't go into a cart and has no pickup or delivery: show the price, the distance and mapsUrl (directions to the store). To track gas prices, search with radiusKm.
• storeVerified: the store's company has an active CNPJ at the Receita Federal (Brazil's tax authority). storeRating and storeRatingCount: average rating (1 to 5) and how many ratings from people who bought through BridgesAgents.
• kind: GOOD (physical product), FUEL, SERVICE, BOOKABLE (travel, reservations) or DIGITAL (course, gift card). Only GOOD goes into a cart; the others are bought through the store's buyUrl.
• currency is the price currency (ISO 4217, e.g. BRL). priceType says how to read the price: FIXED, FROM (starting at), PER_NIGHT, PER_PERSON.
• fulfillment says how it arrives: DELIVERY, PICKUP, IN_STORE (on site), AT_CUSTOMER (at the customer's place), BOOKING or DIGITAL. Services and bookings have no stock (stock is null); digital can be unlimited. Bookings and digital items work from anywhere.
• On the product: taxonomyId (Google Product Taxonomy category), mpn (manufacturer part number) and attributes (type-specific data: color, size, duration_minutes, max_guests...).

Consumer location

Search and offers accept the consumer's location. With it, only stores that deliver there or that are close enough for pickup (up to 30 km) show up, and each offer says how the store serves the consumer.

• Prefer latitude and longitude: they are precise. With only the postalCode (CEP), the coordinates come from a CEP lookup service and are often just the city center; in that case the distance comes with distanceApproximate: true.
• Delivery applies if the consumer is within the store's radius or in one of the CEP ranges it serves. CEP ranges work even without coordinates, so always send the CEP when you have it.

Connect via MCP

The server uses the Streamable HTTP transport at https://api.bridgesagents.com/mcp.

Claude Code

claude mcp add --transport http bridgesagents https://api.bridgesagents.com/mcp \
  --header "Authorization: Bearer abd_SUA_CHAVE"

Clients that only accept local servers (stdio)

Use mcp-remote as a bridge. Example configuration (Claude Desktop, Cursor and similar):

{
  "mcpServers": {
    "bridgesagents": {
      "command": "npx",
      "args": ["mcp-remote", "https://api.bridgesagents.com/mcp", "--header", "Authorization:Bearer ${BRIDGESAGENTS_KEY}"],
      "env": { "BRIDGESAGENTS_KEY": "abd_SUA_CHAVE" }
    }
  }
}

Test without an agent

MCP Inspector lists and runs the tools from the browser. Choose Streamable HTTP, enter the URL above and add the Authorization header with Bearer abd_….

Clients that support OAuth (such as Claude and MCP Inspector) don't need a header: on first access they get a 401 with WWW-Authenticate, discover the authorization server, register themselves and open the page where the consumer signs in (or creates an account) and allows access. See Authentication.

npx @modelcontextprotocol/inspector

MCP tools

[
  {
    "id": "00000000-0000-0000-0000-0000000000b8",
    "gtin": "7890000000103",
    "name": "Amoxicilina 500mg 21 cápsulas",
    "brand": "Marca F",
    "category": "Medicamentos",
    "unit": "UN",
    "requiresPrescription": true,
    "imageUrl": "https://img.example.com/amoxicilina.png"
  }
]

[
  {
    "storeId": "00000000-0000-0000-0000-0000000000a4",
    "storeName": "Farmácia Exemplo Savassi",
    "city": "Belo Horizonte",
    "region": "MG",
    "price": 32.90,
    "promoPrice": null,
    "effectivePrice": 32.90,
    "stock": 20.000,
    "inStock": true,
    "soldByWeight": false,
    "requiresPrescription": true,
    "updatedAt": "2026-10-25T21:51:47Z",
    "stale": false,
    "distanceKm": 0.2,
    "distanceApproximate": false,
    "pickup": true,
    "delivery": { "fee": 0.00, "etaMinutes": 40, "minOrder": null, "coveredBy": "radius" },
    "openNow": true,
    "buyUrl": "https://api.bridgesagents.com/r/00000000-0000-0000-0000-0000000000cb"
  }
]

{
  "id": "f4e2add5-0103-4fc2-aebb-77dbabff2241",
  "status": "OPEN",
  "store": { "id": "00000000-0000-0000-0000-0000000000a4", "name": "Farmácia Exemplo Savassi", … },
  "fulfillment": "PICKUP",
  "items": [
    { "productId": "00000000-0000-0000-0000-0000000000b6", "name": "Protetor Solar FPS 50 200ml",
      "unit": "UN", "quantity": 2, "unitPrice": 52.90, "lineTotal": 105.80 }
  ],
  "subtotal": 105.80,
  "deliveryFee": null,
  "total": 105.80,
  "expiresAt": "2026-10-27T02:39:54Z",
  "confirmUrl": "https://bridgesagents.com/compras/c/abc_…",
  "order": null
}

Prescription products can't go in a cart. If any item has a problem (out of stock, quantity, store doesn't sell it), nothing is created and the response lists each problem. On confirmation, price and stock are checked again: if the price changed, the consumer sees the new amount before confirming.

Upcoming tools: quote_delivery and payment through the agent.

UCP and ACP

The same catalog is also available in Google's and OpenAI's agentic commerce formats. Each product (the same in every store, by GTIN) carries the offers from all stores. The purchase still happens at the store: there is no checkout through the agent yet.

UCP (Universal Commerce Protocol)

The profile at https://api.bridgesagents.com/.well-known/ucp advertises the dev.ucp.shopping.catalog.search and dev.ucp.shopping.catalog.lookup capabilities (version 2026-08-25). Each store offer is a variant: the store is in seller, the price in cents ({"amount": 2490, "currency": "BRL"}), and url is the purchase link. Distance, pickup, delivery and opening hours are in metadata. Pass context.postal_code to see only the stores that serve the consumer.

curl -X POST "https://api.bridgesagents.com/ucp/v1/catalog/search" -H "Authorization: Bearer abd_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"query": "pilha aa", "context": {"postal_code": "30140-010"}, "pagination": {"limit": 5}}'

ACP (Agentic Commerce Protocol, OpenAI)

ChatGPT product feed: one JSON object per line, one line per store offer, with price in the 19.90 BRL format and is_eligible_checkout: false. Offers without a brand, an image or a sales channel are left out (the format requires those fields), as are prescription products. The X-BridgesAgents-Skipped header tells how many were left out.

The feed is for internal use: BridgesAgents itself generates it at /feeds/acp/products.jsonl.gz and sends it to OpenAI. Agents don't need to download it; to query the catalog, use MCP, REST or UCP with the agent key.

Import the catalog

The merchant uploads the spreadsheet they already use, in Excel (.xlsx) or CSV, through the dashboard or the API. Importing again updates price and stock without duplicating products.

• The first row is the header. Column order doesn't matter, and unknown columns are ignored.
• Names are compared ignoring accents, case and punctuation: Preço de Venda and preco_venda are the same column.
• Numbers accept the Brazilian format (1.234,56, R$ 27,90 — R$ is the Brazilian real) and also 27.90.
• CSV can use semicolon, comma or tab as the separator, in UTF-8 or in Excel's default format for Portuguese.
• Rows with problems don't block the others: the result lists each one with its row number and the reason.
• Fuel (gasoline, ethanol, diesel, CNG) is automatically flagged as sold on site only: no cart, it shows up by distance to the station. Weapons, ammunition, explosives, e-cigarettes and drugs are rejected.
• Limits: 5 MB and 10,000 rows per file.

Column headers are recognized by their Portuguese names (the ones in the table and in the template). Yes/no columns also accept yes/no and true/false.

Download the template spreadsheet

Store setup

The merchant is responsible for setting up each store: address, location, how it serves customers and opening hours. That's how agents know whether the store delivers to the consumer, whether pickup is possible nearby and whether it's open. The dashboard shows what's missing in each store.

• Coordinates: enter the exact ones (in Google Maps, right-click the store and click the numbers). If left blank, we use an approximation from the CEP, which may be just the city center.
• Delivery: by radius (km from the store), by CEP ranges or both. Fee, lead time in minutes and minimum order are set per store.
• Sales channel: WhatsApp for orders and/or a website. That's where the “buy at this store” link (buyUrl) takes the customer. On the website, {produto} in the URL is replaced with the product name.
• Opening hours: per day of the week, in the time zone of the store's state (UF). Two shifts separated by a comma, 24h or fechado (closed). Closing after midnight (22:00-02:00) also works.

Store spreadsheet (chains)

In Stores → Import spreadsheet, a chain creates and updates all its stores at once. The code identifies each store: if it exists, it's updated; otherwise, it's created.

As in the catalog, column headers are recognized by their Portuguese names. Days are seg, ter, qua, qui, sex, sab, dom (Monday to Sunday).

* City and UF (state) are filled in from the CEP when left blank. Download the store template spreadsheet

Connect Bling

Merchants who use Bling (a Brazilian ERP) need neither a spreadsheet nor any coding: under Integrations in the dashboard, the admin connects the Bling account, authorizes BridgesAgents (read-only access to products, stock and warehouses) and chooses which warehouse supplies each store.

• Price, photo, barcode, brand and category come from the product record in Bling.
• Each store's stock is the sum of the available balance of the warehouses linked to it.
• Price and stock changes arrive within seconds; a full sync runs every day overnight and shows up under Imports with Bling as the source.
• A product deactivated or deleted in Bling gets zero stock.
• Products with variations (color, size) aren't supported yet: for now, send those through the spreadsheet.

Connect Nuvemshop

Merchants who sell on a Nuvemshop online store (Tiendanube outside Brazil) don't need a spreadsheet either: under Integrations in the dashboard, the admin connects the store, authorizes BridgesAgents (read-only access to products and stock) and chooses which BridgesAgents store receives the stock of each Nuvemshop location (with a single store, this is automatic).

• Each variant becomes an item, named with the product name and the variant values (e.g. "Camiseta Básica – Azul / M").
• Price, sale price, photo, barcode (when it's a valid GTIN), brand and category come from Nuvemshop.
• A variant without stock tracking in Nuvemshop shows as available, with 999 units.
• Product changes arrive within seconds; a full sync runs every day overnight and shows up under Imports with Nuvemshop as the source.
• A product that is hidden, not listed or deleted in Nuvemshop gets zero stock. A variant without a price ("ask for a quote") isn't imported.

Order webhooks

To have the order land straight in the store's system (ERP, POS, scheduling, n8n, Zapier): under Integrations, the account admin or the company developer registers an https address and chooses the store (or all of them) and the events. Admins get an email for every new webhook.

• order.created: the consumer confirmed the order (same moment as the email to the store).
• order.status_changed: the store accepted, got it ready, completed or cancelled it (with cancelReason).
• order.paid: the store marked the order as paid (or undid it: paidAt goes back to empty).
• Each delivery is a POST with the full order in data.order: items with the store's gtin and sku, customer, address, booking or service schedule, totals and currency. New fields may appear; none is renamed.
• Customer data only goes to the order's store. To send the status back, use POST /api/v1/me/orders/{id}/status with the store key.
• Order number: when registering, choose what your system accepts. Digits only: "number": 1042. Letters and digits: "number": "AB1042". The reference field ("AB1042", the same identifier as the Pix and the consumer's link) is always sent.
• Access header (optional): if your system requires a fixed token (Authorization: Bearer …, X-Api-Key...), register its name and value: it goes in every delivery, along with the signature. The value is encrypted and the dashboard only shows its end.
• Developer account: under Webhooks, the agent developer gets the same events for orders placed with their keys, with data.cart (id, externalReference, agentKeyId) and the order without the buyer's personal data (customer and deliveryAddress empty). That's how the bot notifies the user without polling get_cart.

Example

POST https://seusistema.com.br/agentbridge/pedidos
Content-Type: application/json
X-BridgesAgents-Event: order.created
X-BridgesAgents-Event-Id: 6f1c0d2e-…
X-BridgesAgents-Delivery: 0b9a7c41-…
X-BridgesAgents-Signature: t=1793000000,v1=5d2c…
X-Api-Key: (o cabeçalho de acesso, se você cadastrou um)

{
  "id": "6f1c0d2e-…",
  "event": "order.created",
  "createdAt": "2026-10-27T14:03:11Z",
  "data": {
    "order": {
      "id": "…", "number": 1042, "reference": "AB1042", "status": "NEW",
      "storeId": "…", "storeCode": "CENTRO", "storeName": "Exemplo Centro",
      "fulfillment": "DELIVERY",
      "customer": { "name": "Ana Souza", "phone": "+5511988887777", "email": "ana@exemplo.com", "note": null },
      "deliveryAddress": { "postalCode": "01310100", "street": "Av. Paulista", "number": "1000", "complement": null,
                           "district": "Bela Vista", "city": "São Paulo", "region": "SP" },
      "items": [
        { "productId": "…", "gtin": "7890000000011", "sku": "ARZ-5", "name": "Arroz Branco Tipo 1 5kg", "unit": "UN",
          "quantity": 2, "unitPrice": 24.90, "multiplier": 1, "lineTotal": 49.80, "adult": false }
      ],
      "subtotal": 49.80, "deliveryFee": 8.00, "total": 57.80, "currency": "BRL", "estimated": false,
      "schedule": { "scheduledFor": null, "checkIn": null, "checkOut": null, "guests": null },
      "paidAt": null, "cancelReason": null, "agentNote": null,
      "createdAt": "2026-10-27T14:03:10Z", "updatedAt": "2026-10-27T14:03:10Z",
      "payment": { "status": "PENDING", "method": "PIX" }
    }
  }
}

Verifying the signature

When you register, the dashboard shows the secret (whsec_…) once. Each delivery carries X-BridgesAgents-Signature: t=<seconds>,v1=<hex>, where v1 is the HMAC-SHA256, keyed with the secret, of t + "." + body (the body exactly as received). Reject it if it doesn't match or if t is older than 5 minutes.

// Node.js (Express): use o corpo cru, antes de qualquer JSON.parse
import crypto from "node:crypto";

app.post("/agentbridge/pedidos", express.raw({ type: "application/json" }), (req, res) => {
  const header = req.get("X-BridgesAgents-Signature") ?? "";
  const t = header.match(/t=(\d+)/)?.[1];
  const v1 = header.match(/v1=([0-9a-f]+)/)?.[1] ?? "";
  const expected = crypto.createHmac("sha256", process.env.BRIDGESAGENTS_WEBHOOK_SECRET)
    .update(`${t}.${req.body}`).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
  if (!fresh || v1.length !== expected.length
      || !crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected))) {
    return res.sendStatus(401);
  }
  const event = JSON.parse(req.body);
  // Guarde event.id: se chegar de novo (nova tentativa ou reenvio), ignore
  res.sendStatus(200);
});

# Python (Flask)
import hashlib, hmac, os, re, time
from flask import Flask, request, abort

app = Flask(__name__)

@app.post("/agentbridge/pedidos")
def pedidos():
    header = request.headers.get("X-BridgesAgents-Signature", "")
    t = re.search(r"t=(\d+)", header)
    v1 = re.search(r"v1=([0-9a-f]+)", header)
    if not t or not v1 or abs(time.time() - int(t[1])) > 300:
        abort(401)
    body = request.get_data(as_text=True)
    expected = hmac.new(os.environ["BRIDGESAGENTS_WEBHOOK_SECRET"].encode(), f"{t[1]}.{body}".encode(),
                        hashlib.sha256).hexdigest()
    if not hmac.compare_digest(v1[1], expected):
        abort(401)
    event = request.get_json()
    return "", 200

Responses, retries and resending

• Answer 2xx within 10 seconds and process later if it takes long. Redirects are not followed.
• Without a 2xx we retry after 1 min, 5 min, 30 min, 2 h and 12 h. Once exhausted (about 15 h), the webhook is paused and admins get an email; orders stay in the dashboard.
• The same event can arrive more than once (retry or resend): use X-BridgesAgents-Event-Id (same as the body's id) to skip duplicates. Order isn't guaranteed after a failure: compare data.order.updatedAt.
• The dashboard keeps recent deliveries (30 days) with each error, plus Send test (fake order, webhook.test event), Resend, Pause/Resume and Rotate secret.

Testing in the sandbox

In the sandbox you test your agent's whole flow without a real store: stores, products and orders are fictitious, and you play the store and the payment checkout.

• In the dashboard: under Agent orders, open an order and use the buttons to accept, mark ready, complete or cancel it, and to report the payment (paid with Pix, card or boleto, refused, refunded, disputed).
• Through the API, with the agent key (for automated tests): POST /api/v1/carts/{id}/sandbox/status with {"status": "ACCEPTED"} (ACCEPTED, READY, COMPLETED, CANCELLED) and POST /api/v1/carts/{id}/sandbox/payment with {"status": "paid", "method": "pix"} (paid, refused, refunded, chargeback, pending; pix, card, boleto).
• Each simulation really changes the order: the consumer is notified, your webhooks get order.status_changed and order.paid, and get_cart shows order.status, order.paymentStatus, order.paymentMethod and order.paidAt.
• Only orders built by your keys. In production these routes don't exist: the store responds.

# Aceitar o pedido e avisar o pagamento aprovado (sandbox, com a chave de agente)
curl -X POST https://api.sandbox.bridgesagents.com/api/v1/carts/$CART_ID/sandbox/status \
  -H "Authorization: Bearer $BRIDGESAGENTS_KEY" -H "Content-Type: application/json" \
  -d '{"status": "ACCEPTED"}'

curl -X POST https://api.sandbox.bridgesagents.com/api/v1/carts/$CART_ID/sandbox/payment \
  -H "Authorization: Bearer $BRIDGESAGENTS_KEY" -H "Content-Type: application/json" \
  -d '{"status": "paid", "method": "pix"}'

Full toolkit: risk and areas

Developer accounts can see the risk level of the orders their agents generated (GET /api/v1/me/agent-orders/{cartId}/risk) and the numbers by area from the network stores (GET /api/v1/me/insights/regions), and search orders by area (GET /api/v1/me/insights/orders?q=04001, by the start of the postal code or by city or neighborhood name): products and category, payment, refusals and the reason, and the contact (name, email, phone) only from orders with consent: the bot operator collects the buyer's consent, under the clause in its contract with BridgesAgents. What shows depends on what the contract allows, field by field, and every search is logged. Everything is open in the sandbox; in production, under a contract with BridgesAgents.

Send the catalog via API

For the store's system (ERP, online store, script) to send prices and stock automatically, without a spreadsheet. Same rules and messages as the spreadsheet import.

1. Generate the key

There are two kinds:

• Company key (POST /api/v1/me/api-keys): works for all stores. Each item sets storeCode, the store's code in your system. Ideal for chains.
• Single-store key (POST /api/v1/stores/{storeId}/api-keys): everything goes to that store and storeCode is ignored.

In the dashboard, under API keys, or via the API with the merchant session (see Authentication). The full key only appears in that response: store it securely.

curl -X POST "https://api.bridgesagents.com/api/v1/stores/{storeId}/api-keys" \
  -H "Authorization: Bearer abs_…" \
  -H "Content-Type: application/json" -d '{"name": "ERP"}'

{
  "apiKey": { "id": "…", "name": "ERP", "keyPrefix": "abk_Xy12Ab34", "createdAt": "…", "lastUsedAt": null, "revokedAt": null },
  "key": "abk_Xy12Ab34…"
}

2. Send the items with the key

The key goes in the X-Api-Key header. With the company key, each item's store comes from storeCode; with a single-store key, it's always that store. Each item creates or updates the store's offer; items not sent stay as they are (to take one off sale, send stock 0). Up to 1,000 items per request.

curl -X POST "https://api.bridgesagents.com/api/v1/catalog/items" \
  -H "X-Api-Key: abk_…" -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "storeCode": "BH-SAVASSI", "gtin": "7890000000066", "name": "Pilha Alcalina AA com 4", "price": 17.50, "stock": 60 },
      { "storeCode": "BH-PAMPULHA", "gtin": "7890000000103", "name": "Amoxicilina 500mg 21 cápsulas",
        "price": 29.90, "stock": 8, "requiresPrescription": true }
    ]
  }'

The response tells what got in. Items with problems don't block the others and show up in errors with their position in items (starting at 0):

{
  "received": 2, "imported": 1, "failed": 1,
  "productsCreated": 0, "offersCreated": 0, "offersUpdated": 1,
  "errors": [ { "index": 1, "gtin": null, "name": "Banana Prata", "message": "Preço em branco." } ]
}

To replace a leaked key, generate a new one and revoke the old one in the dashboard (or with DELETE /api/v1/stores/{storeId}/api-keys/{keyId}).

REST API

Responses in JSON. Product and offer fields are the same as in the MCP tools.

curl -H "Authorization: Bearer abd_SUA_CHAVE" "https://api.bridgesagents.com/api/v1/products?q=pilha%20aa"

curl -H "Authorization: Bearer abd_SUA_CHAVE" \
  "https://api.bridgesagents.com/api/v1/products/00000000-0000-0000-0000-0000000000b7/offers?postalCode=30140-010"

curl -X POST "https://api.bridgesagents.com/api/v1/carts" -H "Authorization: Bearer abd_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"storeId": "00000000-0000-0000-0000-0000000000a4", "fulfillment": "pickup",
       "items": [{"productId": "00000000-0000-0000-0000-0000000000b6", "quantity": 2}]}'

With a merchant session (header Authorization: Bearer abs_…)

curl -H "Authorization: Bearer abs_…" -F "file=@catalogo.xlsx" \
  "https://api.bridgesagents.com/api/v1/stores/{storeId}/catalog/import"

With a store API key (header X-Api-Key: abk_…)

{
  "rows": 120,
  "imported": 118,
  "failed": 2,
  "productsCreated": 40,
  "offersCreated": 100,
  "offersUpdated": 18,
  "ignoredColumns": ["Observações"],
  "errors": [
    { "line": 7, "message": "Preço inválido: \"abc\"." },
    { "line": 31, "message": "Nome do produto em branco." }
  ]
}

To try the endpoints right in the browser, use the interactive reference (Swagger).

Errors and limits

Errors use the application/problem+json format (RFC 9457). The detail field carries a message in Portuguese that can be shown to the merchant.

The API's detail messages are always in Portuguese; the BridgesAgents dashboard translates them. If you show them to users in another language, map them by the HTTP status or translate them on your side.

Authentication

Agent key

No catalog query is anonymous. Create a developer account (no CNPJ needed) and generate keys under Agent keys in the dashboard. The key is shown only once; the database stores only its hash. Use one key per agent or environment: if one leaks, revoke just that one. The dashboard shows how many requests each key made per day, and the limit is 120 per minute per key.

curl -X POST "https://api.bridgesagents.com/api/v1/me/agent-keys" -H "Authorization: Bearer abs_…" \
  -H "Content-Type: application/json" -d '{"name": "Agente em produção"}'
# → { "apiKey": { "id": "…", "keyPrefix": "abd_Xk3…" }, "key": "abd_…" }   (só desta vez)

Plans and quota

Each request authenticated with an agent key counts as one request (search, offers, cart or MCP call). The Free plan includes 10,000 requests per month; once you reach them, the API returns 429 with the explanation in detail until the 1st of the next month. Paid plans (Pro and Scale) don't block: overage is billed per 1,000 requests on the end-of-month invoice. We email you at 80% and 100% of the quota, and this month's usage shows under Plan and billing in the dashboard. The sandbox has no quota.

Sandbox

To test without touching real stores, use the sandbox: site at https://sandbox.bridgesagents.com and API at https://api.sandbox.bridgesagents.com (MCP at /mcp). It runs the same version as production (every change is published to both), but with its own database of sample stores and products. Create a developer account there: keys start with abd_test_ and don't work in production (nor do production keys work there). Carts and orders work end to end, only at the sample stores; emails arrive with [Sandbox] in the subject.

OAuth 2.1 (MCP server)

We follow the MCP specification's authorization: metadata at /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server, dynamic registration at POST /oauth/register (public clients only), authorization code with mandatory PKCE S256 at /oauth/authorize and POST /oauth/token. The access token (abo_) lasts 1 hour and the refresh token (abr_) 30 days, rotated on every use; reusing a refresh token or a code drops the connection. POST /oauth/revoke revokes. Consumers see and disconnect apps under My purchases › Connected apps.

Only discovery (/.well-known/ucp), this documentation and the purchase link /r/…, which the consumer opens, are public.

Dashboard session

The session comes from login and lasts 30 days:

curl -X POST "https://api.bridgesagents.com/api/v1/auth/login" -H "Content-Type: application/json" \
  -d '{"email": "voce@sualoja.com.br", "password": "…"}'
# → { "token": "abs_…", "expiresAt": "…", "user": { … } }

Merchant sign-up (POST /api/v1/auth/signup) creates the company, the first store and the user at once; developer sign-up (POST /api/v1/auth/signup/developer) asks only for the company or project name, your name, email and password. Both return the session right away. POST /api/v1/auth/logout ends the session.

The agent key still works for agents that don't use OAuth.