--- name: using-bazantic description: >- Use when an agent needs a paid third-party API without a provider key, needs a published Recipe for a multi-tool task, manages Bazantic gateways or Recipes, or uses the baz CLI. Also use before direct provider signup, custom x402 payment code, or a guessed gateway URL. --- # Using Bazantic Bazantic gives agents typed API tools and pay-per-call access. The gateway holds a provider credential when the upstream needs one. A caller uses a Bazantic grant or self-custody wallet. Use one of these surfaces: | Need | Surface | | --- | --- | | Find one API | [Service catalog](https://bazantic.com/services), or `baz search ` | | Read the price of one call | `baz check ` (pays nothing) | | Run a task that uses multiple tools | [Recipe catalog](https://bazantic.com/recipes) | | Inspect typed tools for one service | The service MCP server | | Pay for a call | `baz curl` | | Pay for a call from an MCP client | `baz mcp install --client `, then the `fetch` tool | | Manage gateways or Recipes | The `baz` CLI or dashboard | ## Install the CLI and this skill Install the current CLI: ```bash npm i -g @bazantic/cli baz --version ``` Run `baz update --check` to check for a newer release. Run `baz update` to install it. Download and review this skill before you install it for Claude Code: ```bash curl -fsSL https://bazantic.com/skill -o /tmp/using-bazantic-SKILL.md less /tmp/using-bazantic-SKILL.md mkdir -p .claude/skills/using-bazantic install -m 0644 /tmp/using-bazantic-SKILL.md .claude/skills/using-bazantic/SKILL.md ``` This example limits trust to the current project. Other agents can use the reviewed file in their supported skills directory. ## Safety rules - Do not ask for a provider API key. Bazantic stores that credential for the provider. - Do not paste private keys, device keys, session tokens, or provider credentials into a prompt. - If a secret appears in a prompt, do not repeat it. Tell the owner to revoke or rotate it. - Do not print `~/.bazantic/config.json`. It can contain credentials and session data. - Do not build an x402 or MPP payment header. Use `baz curl`. - Do not build a gateway URL. Read the advertised URL from the catalog or CLI. - Check the response body. A provider can return a chargeable application error with HTTP 200. - Use a spend grant for an agent when possible. Set a low per-call ceiling. - Limit the grant to one provider with `--service` when the task needs one service. - Read the free catalog and specification first. Confirm that the service answers the request. - Get user approval for the task, expected price, and side effects before the first paid call. - Get user approval before any upstream call that can create, update, or delete data. - A per-call ceiling is not a task budget. Use the grant cap to limit total authorized spend. - Get explicit approval before config edits, gateway activation, or Recipe lifecycle changes. - Ask a human to approve sign-in and grant requests. An agent cannot approve its own authority. - Do not put secrets in a Recipe prompt, draft, input example, or test input. ## Sign in for management The management session cannot spend money. ```bash baz login baz whoami ``` `baz login` prints an approval URL and waits. Give the URL to the human. Continue only after the human approves the request. An agent needs no flag for correct behaviour here. The CLI opens a browser only when three conditions hold. The `CI` variable is empty. Stdin and stderr are both a terminal. The command has no `--json` flag. An agent reads a pipe, so the CLI prints the URL and waits. Two flags override that rule. Only `baz login` and `baz grant create` accept them: - `--browser` opens the page although the CLI reads a pipe. Use it when the agent and the human share one machine. - `--no-browser` never opens the page. Use it when the human works at a different machine, such as a remote container. `--no-browser` wins over `--browser`. `baz login` prints no fingerprint. `baz grant create` prints one, because a grant carries authority to spend. Gateway and Recipe management need this session. A self-custody wallet does not need a Bazantic account. ## Discover a service before payment Start with the [service catalog](https://bazantic.com/services). Use the advertised gateway URL. Do not derive a URL from a name or slug. For a gateway that you own, read `endpointUrl` from structured output: ```bash baz gateway list --json ``` Use these machine resources when the listing provides them: - The OpenAPI or OpenRPC specification describes the HTTP or JSON-RPC contract. - The MCP server lists typed tools for the service. - The A2A agent card describes the MCP server and its tools. The Bazantic discovery catalog returns the A2A link in `agentCard`. The service page shows the same machine resources. Do not guess a well-known URL. An MCP `tools/list` request is free. A `tools/call` request can invoke the upstream service. Inspect the tool and price before a call. A normal MCP client cannot settle a priced tool. Use `baz curl`, or the `fetch` tool of `baz mcp`, for a paid service call. `baz curl` takes the curl flags that agents type. It names an ignored flag on stderr. A flag that it cannot do stops the call with exit code 2, before any payment. ### Confirm the capability before payment Read the specification first. A catalog read, a specification read, and a `tools/list` request all cost nothing. Read the price of the endpoint before the first paid call. `baz check ` takes the `baz curl` flags, sends the request once with no payment, and lists each offer in the 402. A free endpoint answers normally, so a check of a free `POST` runs that `POST`. Confirm that one endpoint answers the user request. A paid call to the wrong endpoint settles the payment and returns data that does not answer the request. Name the limits of the service to the user before the first paid call. A service that reports live aircraft positions does not publish a timetable or a fare. A user who wants a schedule needs a different source. State this before payment, not after. ## Pay for one service call Every price, cap, and ceiling uses USD units. Base uses USDC. Tempo uses its network USD token. The CLI checks the ceiling before it signs and retries the request. Prefer a capped grant. Limit the grant to the one provider that the task needs: ```bash baz grant create --name agent-1 --cap 5 --service baz curl "${ENDPOINT_URL}/path" --account agent-1 --max-amount 0.02 --json ``` `--service ` limits the payees to the deposit addresses of the provider account that owns that gateway. That provider can take payment for each of its gateways, so the limit is the provider and not the one gateway. A grant without `--service` pays Bazantic providers. For an external service, use a canonical HTTPS origin and pin the public payment recipient: ```bash baz grant create --service https://stabletravel.dev --recipient 0x1111111111111111111111111111111111111111 --network base --name flights --cap 0.10 --max-per-request 0.05 ``` The target command requires `--name`, `--cap`, `--recipient`, `--network`, and `--max-per-request`. The relay enforces the recipient, network, USDC token, request cap, and total cap. The origin is an approval label and a CLI request check. It does not prove a challenge origin. Use `--any-service` only when the task needs any supported external USDC recipient. Take the slug from the `slug` field of the public catalog at `https://api.bazantic.com/v1/gateways`. A service page address carries the marketplace handle, which is a different value. `baz gateway list --json` needs a session and returns your own gateways only, so use it for a gateway that you own. The grant request needs browser approval. Show the approval URL and fingerprint to the human. Wait for approval before the call. The cap is the total spend for the life of the grant. The ceiling is the limit for one call. Set both. Use `--json` for agent workflows. The upstream response is in `.body`. The `.paid` object contains the settlement details. The default `--max-amount` is `0.01`. Set an explicit ceiling when the expected price is different. The ceiling check happens before the CLI signs a payment. Use `--yes` only for a task that the user already approved for unattended execution. The grant cap remains the total spend limit. ### Payment sources and networks | Source | Networks | Use | | --- | --- | --- | | Grant | Base and Base Sepolia | Capped and revocable agent authority | | Self-custody wallet | Base, Base Sepolia, Tempo, and Tempo Moderato | Direct wallet control or MPP | A standard grant uses one shared cap for Base and Base Sepolia. The gateway selects the payment network. An existing grant can pay both live and sandbox gateways. A sandbox gateway requests Base Sepolia USDC. `baz curl` selects Base Sepolia from the payment request. Do not force `--network base` for a sandbox gateway. Tempo uses MPP and needs `--account wallet`. A grant cannot pay on Tempo. Inspect or revoke grants with these commands: ```bash baz grant list --json baz grant revoke agent-1 ``` An explicit unknown `--account` is an error. The CLI does not silently replace it with the self-custody wallet. ## Use a Recipe for a complete task A Recipe publishes one task as one MCP tool. Each Ingredient is a service tool that the Recipe can call. Search the public catalog before you write a chain of service calls: ```bash curl -fsSL https://api.bazantic.com/v1/recipes ``` Catalog reads need no key or payment. Review the input schema and examples before a paid call. Install the live Recipe catalog in one supported MCP client: ```bash baz recipe install --client claude-code # or: baz recipe install --client codex # or: baz recipe install --client cursor ``` The adapter reads the current public catalog. The adapter also pays for Recipe calls with the configured grant or wallet. Set `gateway.maxAmountUsd` in the CLI configuration before an unattended call. If a valid management session exists, the adapter also provides authorized `bazantic_*` tools. These tools manage Recipes and discover eligible Ingredients. Management tools do not spend money. ### Create and publish a Recipe Use the dashboard to draft and test a Recipe. The editor can draft a Recipe from a task description. Review its prompt, inputs, and Ingredients before publication. A Recipe test can call live upstream tools. Use non-sensitive fixtures. Get approval before a test can create, update, or delete upstream data. A free test can still change data. Use the CLI when you already have a strict Recipe JSON file: ```bash baz recipe create ./recipe.json --json baz recipe publish --json baz recipe list --json ``` Run `baz recipe --help` for the current fields, limits, model values, and lifecycle commands. The server derives the immutable handle from the Recipe name. Published definitions are not editable. Unpublish a Recipe before an update. Delete applies to a draft. ## Register a provider API Use an OpenAPI or OpenRPC document and an HTTPS upstream URL: ```bash baz gateway add \ --spec-url https://api.example.com/openapi.json \ --endpoint https://api.example.com \ --name "Example API" \ --auth-type none \ --status draft \ --json ``` The specification URL must be public. Use the dashboard when the specification has no public URL. Use only the supported upstream authentication modes: - `none` for an upstream that needs no credential. - `api-key` for an API key, bearer token, query parameter, or URL credential. - `basic` for Basic authentication. Do not pass a credential on the command line. Add the credential and its delivery rule in the dashboard. Prefer bearer delivery or a dedicated header. Use a query parameter or URL credential only when the provider requires it. Review the methods and prices before activation. The CLI creates an active gateway by default. `--status draft` prevents traffic. Use `baz gateway activate ` when the draft is ready. Get owner approval before you activate a gateway. The generated MCP server needs a compatible pair: OpenAPI with REST, or OpenRPC with JSON-RPC. Confirm the MCP server with `tools/list` before you give it to another agent. ### Keep paid routes aligned with the specification Replace the stored specification in the dashboard. Then compare it with the paid routes: ```bash baz gateway resync ``` The command shows added, removed, and unchanged routes. It preserves the price of each unchanged route. A removed route stops serving after confirmation. Check active callers and review the removal list first. Use `--json` for a read-only preview. Use `--yes` only after you review the same change. ### Test without real funds Get owner approval before you change sandbox mode. Turn it on from the gateway actions menu. The change applies to all callers until an owner turns it off. The public URL stays the same. A sandbox gateway requests Base Sepolia USDC. The same grant can pay before and after this change. Fund the hosted balance address with Base Sepolia test USDC before a sandbox call. The dashboard **Balances** page gives the address. Sandbox funds do not appear in the production balance. ### Inspect gateway activity Open **Analytics** in the dashboard. Filter by gateway, operation, surface, or time range. The view shows payment states, call outcomes, reported MCP clients, and recent sampled calls. Use the recent rows for diagnosis, not as a complete audit log. Known test networks do not count toward revenue. ### Use a custom hostname A custom handle gives the gateway a readable `bazgateway.com` hostname. Claim it in the dashboard. A custom domain uses a hostname that the provider controls. Manage a custom domain with these commands: ```bash baz gateway domains add api.example.com baz gateway domains status baz gateway domains verify ``` Create the DNS records that Bazantic returns. Keep the permanent slug URL. It continues to serve after a custom hostname becomes active. ## Command summary ```text baz login | logout | whoami baz gateway add | list | activate | resync baz gateway domains add | status | verify | rm baz recipe list | get | create | update | publish | unpublish | delete baz recipe install | mcp baz curl [options] baz wallet new | import | address | balance baz grant create | list | revoke baz update [--check] ``` Run `baz --help` for current options. Use the current CLI instead of version-specific workarounds from older releases. ## Handle Recipe errors Read [MCP errors](https://bazantic.com/docs/mcp-errors) for error meanings and recovery steps. Show `error.message` when present. Use `error.code` for program logic. Obey `error.next_action`, `retryable`, and `retry_after_seconds`. An absent `execution_started` field means the execution status is unknown. Do not repeat a call with possible external effects until you verify its result. `usage_unavailable` means Bazantic could not check account usage before execution. It does not prove a credit shortage or an expired connection. Retry once after a short delay. If the error persists, stop and report it. Do not call other Recipes to bypass an account-wide failure. Never present an error as an empty wallet, zero balance, or successful result. ## Fallback If Bazantic does not offer the needed service or Recipe, say so. Use a direct provider only after the user accepts its signup and secret-management cost. Do not force Bazantic onto a public, free, keyless API. Use the simplest safe path that meets the request.