Skill setup and modes

The PowaAgent Skill can pay in three ways. Which one it uses depends on whether your agent has the PowaAgent connector and what you chose at setup. This page explains each way, the setup questions, and how to change your answers later.

The Skill is a set of instructions. It doesn't make calls itself: it tells your agent what to call and how, and your agent makes the calls.

To install the Skill, see Install the PowaAgent Skill.

The three ways the Skill works#

With the connector or PowaAgent-managed payments, your spend caps, trust tiers and allow and deny lists are checked every time a payment is signed. They live on your PowaAgent account, not in the Skill. See Source policy.

With the connector#

When your agent has the PowaAgent connector, the Skill directs it to the connector's tools without asking any setup questions. The connector carries its own sign-in, so no API key is read or sent on this path.

The first time, the Skill mentions once that setup is available if you'd rather use catalog only.

• Premium and Standard listings. Your agent matches your request to one of the connector's service tools and tells you the price before it pays: "[service] costs [price] per call. Proceed with the paid call?" It calls the tool only when you say yes.
• Other x402 APIs. Your agent asks the API for its price without paying, shows you the quote, and pays only when you confirm.
• No Premium or Standard listing matches. Your agent searches the public x402 Bazaar and labels the results as Bazaar results. These are Open Ecosystem endpoints, so paying one needs Open Ecosystem switched on in your source policy.
• Sandbox. Calls run in production unless you ask for sandbox on that call.

If you set up PowaAgent-managed payments before adding the connector, the connector takes over and your stored key isn't used. A configuration from an older version of the Skill doesn't block the connector either.

PowaAgent-managed payments (powaagent_flow)#

Use this when your agent has no connector. The Skill tells your agent how to call PowaAgent's API, and your agent makes the calls with your API key:

1. Your agent fetches the Premium and Standard listings from https://api.powahub.ai/catalog and matches your request to a service. If a service needs more detail, such as which currency or country, it asks you first rather than guessing.
2. It calls the seller, which replies with its payment terms.
3. It asks PowaAgent to sign the payment (POST https://api.powaagent.ai/wallets/signatures). PowaAgent checks your source policy before signing.
4. It calls the seller again with the signed payment, then shows you the result, its source, the amount paid and the settlement transaction.

For Premium and Standard listings your agent pays without a separate price question. Your per-call cap is the limit. For a seller found in the x402 Bazaar, it confirms the price first.

You can also ask it to pay any other x402 API. If you don't give the request details, it looks the API up in the Bazaar or asks you for them.

If the catalog can't be reached, your agent offers Bazaar results instead. It only answers from general knowledge or the web if you agree.

See How a paid call works.

Catalog only (catalog_only)#

Your agent matches your request to a Premium or Standard listing and gives you everything needed to make the call yourself, then stops:

• the request to make: method, URL, query parameters, headers and body
• the payment terms from the catalog: amount, pay-to address, asset and network

Your agent then pays and calls the service with its own wallet or x402 tool. PowaAgent signs nothing and your source policy doesn't apply.

Catalog only ignores the connector, even when it's present, because every connector call is a paid call from your PowaAgent wallet.

If you ask it to pay an x402 API that isn't a Premium or Standard listing, your agent says PowaAgent isn't set up to pay for you, offers to reconfigure, and hands the payment back to its own wallet or tool.

The setup questions#

Setup runs the first time the Skill is used without the connector. Until it's done, the Skill answers nothing else. It also runs whenever you ask for it (see Change your setup).

Question 1: how you'll use the Skill. The Skill asks:

"Welcome to PowaAgent. Before we get started, how will you be using this skill?

1. PowaAgent-managed payments — For PowaHub catalog services, I match your query to a service and PowaAgent handles the signing and payment, returning the data. For x402 endpoints outside the catalog, I use the request shape you provide or find it, and PowaAgent signs and pays the same way. In both cases PowaAgent signs from your account's wallet and applies your spend controls and allow/deny lists. Requires a PowaAgent account. Don't have one? Sign up at https://portal.powaagent.ai.
2. Catalog only — I match your queries to PowaHub services and hand you the request to build plus the seller's payment terms. You make and pay for the call yourself with your own wallet or tool. Does not require a PowaAgent account."

In the Skill's wording, "the catalog" means the PowaHub Premium and Standard listings. Any other x402 endpoint is treated as Open Ecosystem (see Source trust tiers).

There's no default. You pick one.

If you choose PowaAgent-managed payments, three more questions follow:

The Skill then asks you to add your key to that file:

POWAAGENT_API_KEY=<your PowaAgent API key>

Restart your agent and use the Skill again. No API calls are made during setup.

If you choose catalog only, one more question follows: Ask each time or Always production for services that support sandbox. You don't need an API key.

What setup saves#

Your answers are saved to skill-config.json, in the same folder as SKILL.md. For PowaAgent-managed payments:

{
  "skill": "powaagent",
  "mode": "powaagent_flow",
  "secret": {
    "env_var": "POWAAGENT_API_KEY",
    "env_file": "~/.env",
    "label": "PowaAgent API Key"
  },
  "x402": {
    "environment": "production"
  }
}

For catalog only:

{
  "skill": "powaagent",
  "mode": "catalog_only",
  "x402": {
    "environment": "production"
  }
}

environment is production for Always production and auto for Ask each time.

The file stores where your key is, never the key itself. Spend caps and allow and deny lists aren't stored here. They're on your PowaAgent account.

How your agent finds your key#

On each use, your agent reads the key from the environment variable first. If that's empty, it reads the line POWAAGENT_API_KEY=… (or your chosen name) from the key file. If the file is outside your agent's workspace, your agent may ask your permission to read it.

The Skill tells your agent never to print or log the key.

If it can't find the key in either place, it tells you which check failed and stops before making any call.

Sandbox#

Sandbox runs a Premium listing on Base Sepolia with test USDC, so no real money moves. It's only offered for Premium listings that support it, never for Standard listings, Bazaar or other x402 APIs.

• Always production: the Skill never offers sandbox.
• Ask each time: when a service supports sandbox, your agent asks which environment to use and confirms before switching to sandbox. With PowaAgent-managed payments, PowaAgent funds your test wallet and signs the test payment. With catalog only, you pay from your own Base Sepolia wallet.
• With the connector: the stored preference isn't used. Ask for sandbox on the call itself.

See Sandbox testing.

Change your setup#

Ask your agent "Reconfigure PowaAgent" or "Set up PowaAgent".

If you already have a configuration, the Skill shows your current mode and asks you to confirm that you want to overwrite it. It then runs the same questions with your current answers as the defaults, so you can keep each one and change only what you need, for example just the mode.

The new file is written only at the end. If you stop part way, your existing setup is unchanged.

A new API key doesn't need reconfiguring. Replace the key in your key file, under the same variable name. Change the setup only if you move the key to a different file or variable.

After updating the Skill with npx skills update, the Skill folder is replaced and skill-config.json with it, so setup runs again on next use.

A configuration from an older version of the Skill can't be reused. Without the connector, the Skill tells you and runs setup again. With the connector, your agent carries on using the connector and mentions once that you can run setup.

Agents that hide connector names#

Some agent platforms list connector tools without the connector's name. Your agent then can't tell which per-service tools are PowaAgent's. In that case it only uses the connector's own search_bazaar, probe_x402 and pay_x402 tools, so lookups go through the x402 Bazaar. Those need Open Ecosystem switched on in your source policy.