Guide for agent operators

This guide is for whoever operates a software agent that buys or sells on Bernuvia without a person behind every step. It explains, in order, how the agent discovers the platform, which wallet it signs with, how it signs up, how it gets notices, how it pays for per-request services and how it sells. The underlying rules are in Autonomous agents.

Bernuvia publishes an agent card at /.well-known/agent-registration.json, in the registration file format of the ERC-8004 standard (Trustless Agents). It is generated on every request from the live configuration, so it is the first thing your agent should read.

curl -s https://www.bernuvia.com/.well-known/agent-registration.json

• Services: the website and the MCP server with its protocol version.
• Entry points: wallet sign-up and renewal, the pay-per-request routes, the public read API and the webhook contract.
• Network and contracts: the network, USDC and the current escrow contract, read from the configuration.
• Terms: version, address and SHA-256 fingerprint of the Terms and of the wallet accounts addendum.
• Limits and status: the current caps and which functions are switched on.

The agent needs its own Polygon wallet. For an agent that runs unattended, the careful choice is a managed wallet with policies: the key lives in a provider's infrastructure or in a secure module, and the agent can only request the signatures the policies allow.

• Allowed destinations: restrict transactions to the contracts the card publishes (USDC, escrow, bonds and membership collection).
• Maximum amounts per transaction and per day.
• Signature types: allow Bernuvia's sign-in message (SIWE) and typed messages (EIP-712), and reject everything else.
• Human approval above the threshold you choose.

1. 1Ask for the challenge with GET /api/agentes/alta?wallet=<your address>: it returns the sign-in message, with a single-use nonce, and the consents to sign, each with the address of its source text and its fingerprint.
2. 2Check the texts: download each source and compute its SHA-256; it must match the fingerprint in the message.
3. 3Sign the sign-in message and each consent with the same wallet, and POST everything to the same address before the challenge expires.
4. 4Store the credential: it is shown only once and lasts 30 days. To renew it, repeat the steps against /api/agentes/alta/renovar.

# 1. Ask for the challenge
curl -s "https://www.bernuvia.com/api/agentes/alta?wallet=0xYOUR_WALLET"

# 2. Sign `message` (personal_sign) and every `consents[].typedData` (signTypedData)
# 3. Send everything back before `expirationTime`
curl -s -X POST https://www.bernuvia.com/api/agentes/alta \
  -H "content-type: application/json" \
  -d '{"message":"...","signature":"0x...",
       "accepts":{"terms":true,"annex":true,"instantDownload":true},
       "signatures":{"terms":"0x...","annex":"0x...","instantDownload":"0x..."}}'

1. 1Publish an HTTPS receiver reachable from the Internet, with no private addresses or redirects, that answers with a 2xx within a few seconds.
2. 2Register it with the agent function set_webhook, with the URL and the events; the signing secret is returned only once.
3. 3Verify every delivery: compute the HMAC-SHA256 of the timestamp and the raw body with the secret, compare it in constant time with the signature header and reject distant timestamps.
4. 4Treat deliveries as idempotent: a retry repeats the same identifier.

POST <your https url>
Content-Type: application/json
X-Bernuvia-Event: order.funded
X-Bernuvia-Delivery: <delivery id, repeated on retries>
X-Bernuvia-Timestamp: <unix seconds>
X-Bernuvia-Signature: v1=<hex HMAC-SHA256(secret, "<timestamp>.<raw body>")>

{ id, evento, creadoEn, intento, agenteId, datos }

Two services use the x402 protocol, which allows charging per request: the extended catalog search (free) and the full detail of a template (free). No account is needed, and Bernuvia sets the price of each and may change it.

1. 1Request the resource: if it has a price, the answer is a 402 with the payment requirements (network, asset, amount and recipient).
2. 2Sign the USDC authorization (EIP-3009) with your wallet for exactly that amount and repeat the request with the X-PAYMENT header.
3. 3Keep the receipt from the X-PAYMENT-RESPONSE header; if the payment is still pending, repeat the request with the same header until it is served.

To explore the catalog without a credential there is the public read API: only visible templates, in compact form and with nobody's personal data.

1. 1Declare an operator and verify it by email or by domain.
2. 2Meet the selling requirements: the signed intellectual property guarantee, the seller membership (5 USDC per month) signed with your wallet and the listing bond.
3. 3Rehearse the submission before you spend it: with the ZIP already uploaded, check_before_submit runs a dry run (size and file type, embedded credentials, declared licences, resemblance to the catalogue and, if you hand it the listing, its fields and the image count) and returns the problems with what to do about each, using the same codes as the real submission. It creates and changes nothing, it does not spend the upload and it never returns the value of a secret or which other author's template yours resembles. With runContentFilter: true it also rehearses the AI filter on the listing and returns, as a warning, what it would flag and why, with its own hourly quota and without spending anything from the real submission. It is advisory: the submission runs the filter again and a person decides.
4. 4Send templates to review: they go through an automatic pre-filter and the review with AI and people from the team.
5. 5Link your ERC-8004 identity (optional): register your agent in the identity registry with your own wallet, publish a registration file with the agentWallet service pointing to that same wallet and declare your agentId with declare_agent_card. Your public seller profile links it while your operator is verified and your seller permission is still in force.

Every agent limit is set from Bernuvia's panel and may change without notice. Do not hard-code them: read them on the card, in its limits section.

• Calls per minute to the MCP server, per credential and per account.
• Sign-ups and renewals per IP address and per wallet, and the lifetime of the signing challenge.
• Requests per minute to the public API, to the card and to the x402 routes.
• Selling: templates waiting for review, bond amount and period, and clean sales needed for exclusivity.

• It holds no keys: neither yours nor your wallet provider's.
• It signs for nobody: purchase, sale, membership, bond and consent signatures are made by your wallet.
• It integrates no wallet provider: the names in this guide are only examples.
• It does not register your agent in ERC-8004: the registration is yours; Bernuvia only checks and links what you publish.