# How to connect Square to Hermes Agent (no API keys)

> Connect Square to Hermes with ClawLink in one click — 122 tools your AI agent can call from chat via hosted OAuth. No API keys, no manual setup.

Web version: https://claw-link.dev/hermes/square

Most guides for giving Hermes Agent Square access start with registering your own OAuth app or pasting API keys into env files, then leave the token refresh and tool wiring to you. ClawLink gives Hermes a more practical Square setup: pair once in the browser and your always-on Hermes agent can act on Square for you, reading and doing real work on your behalf with no auth, token refresh, or tool wiring to build yourself.

**Start here — paste this into Hermes to set up ClawLink:**

> Set up ClawLink for Hermes and tell me when it's ready.
> 1. Install the plugin: `hermes plugins install ClawLink-HQ/hermes-plugin --enable`
> 2. Start pairing with `hermes clawlink begin`. It prints an approval link, so show me the link and stop, don't wait.
> 3. I'll approve it in my browser, then reply "approved".
> 4. When I say approved, finish setup: `hermes clawlink finish`
> 5. Then run `hermes clawlink test` and tell me whether ClawLink is ready.

## Setup

It takes three steps to connect Hermes to Square.

1. **Install ClawLink** — add the plugin to Hermes Agent once.
2. **Connect Square** — one-click OAuth in the ClawLink dashboard.
3. **Use it from chat** — ask Hermes Agent in plain English.

**Alternative for any agent (no plugin needed):** if the Hermes Agent plugin route isn't available or doesn't work, any AI agent with shell access can use the ClawLink CLI instead:

```bash
npx -y @useclawlink/cli login          # sign in via browser — no API key to paste
npx -y @useclawlink/cli connect square  # connect Square (browser OAuth)
npx -y @useclawlink/cli actions square  # list available actions
npx -y @useclawlink/cli run square <action> --input '<json>'  # execute (add --confirm for writes)
```

### Install by command

The prompt above walks Hermes through this. By hand, it is four commands and a browser approval:

```bash
hermes plugins install ClawLink-HQ/hermes-plugin --enable
hermes clawlink begin    # prints an approval link — open it and approve
hermes clawlink finish   # after approving in the browser
hermes clawlink test
```

Then connect Square in the [ClawLink dashboard](https://claw-link.dev/dashboard) — a one-click OAuth approval, no API keys.

Verify the connection by asking Hermes:

> Run square_list_payments for my locations covering yesterday, group the payments by location, and tell me gross, refunds, and net for each. Flag any payment whose status is not COMPLETED. Do not change anything.

### Using a different agent?

The Hermes plugin is one client of ClawLink's MCP server. Claude Code, Cursor, Codex, or any agent that can run a shell command pairs with the same ClawLink account through the CLI:

```bash
npx -y @useclawlink/cli login
```

`login` opens the same browser approval and stores a credential locally. Once Square is connected in the dashboard, that agent calls the same 122 Square tools over MCP. Full setup for MCP clients and shell agents: [connect apps to any AI agent](https://claw-link.dev/learn/connect-apps-to-any-ai-agent).

## Square MCP for Hermes

Looking for a Square MCP server for Hermes Agent? ClawLink connects Square to Hermes Agent and exposes 122 Square tools your agent can call over [MCP](https://claw-link.dev/learn/what-is-an-mcp-server), with [hosted auth](https://claw-link.dev/learn/oauth-for-ai-agents) and nothing to run or maintain yourself. Using OpenClaw instead? The [OpenClaw Square integration](https://claw-link.dev/openclaw/square) works the same way.

This page ranks third for its own head query, and the AI Overview on that query still teaches searchers to install the Composio CLI and paste an MCP config block into Hermes Agent chat. ClawLink is the browser route: pair Hermes Agent once, approve Square access through Square's own OAuth screen, and 122 tools work from chat with no CLI, no MCP server, and no developer app. The trade to understand up front is scope: the official Square MCP server runs against a developer app you create and manage, with sandbox and production access tokens; this connection is an OAuth grant against your Square seller account, so the agent acts on your real store data, which is why the reads-first prompts below and the ask-before-write pattern matter.

## What the Hermes Agent Square integration can do

122 Square tools are ready for Hermes Agent once the account is connected. The 30 below are the ones people reach for most; your agent can call all 122.

### 30 of 122 Square tools for Hermes

| Tool | What it does |
|---|---|
| **Create customer** `square_create_customer` | Create a new customer profile in Square. |
| **Create order** `square_create_order` | Create a new order in Square. |
| **List customers** `square_list_customers` | List customer profiles in Square. |
| **List invoices** `square_list_invoices` | List Square invoices. |
| **List locations** `square_list_locations` | List business locations in Square. |
| **List payments** `square_list_payments` | List payments in Square. |
| **List subscriptions** `square_list_subscriptions` | List Square subscriptions. |
| **Retrieve customer** `square_retrieve_customer` | Get a Square customer by ID. |
| **Retrieve order** `square_retrieve_order` | Get a Square order by ID. |
| **Search catalog objects** `square_search_catalog_objects` | Search catalog objects in Square. |
| **Update customer** `square_update_customer` | Update an existing Square customer. |
| **Calculate order** `square_calculate_order` | Preview order pricing without creating an order |
| **Get booking** `square_get_booking` | Retrieves detailed information about a specific Square booking by its ID |
| **Get business booking profile** `square_get_business_booking_profile` | Retrieve the business booking profile for a Square merchant via GraphQL |
| **Get current merchant** `square_get_current_merchant` | Retrieve merchant information associated with the access token using Square's GraphQL API |
| **Get customer custom attribute** `square_get_customer_custom_attribute` | Retrieves a custom attribute from a customer profile in Square |
| **Get customers custom attribute definitions** `square_get_customers_custom_attribute_definitions` | Retrieve a customer-related custom attribute definition from Square |
| **Get customers graphql** `square_get_customers_graphql` | Retrieve customer profiles from Square Customer Directory using GraphQL API |
| **Get dispute evidence** `square_get_dispute_evidence` | Retrieves detailed information about a specific piece of evidence that was uploaded for a |
| **Get gift card from gan** `square_get_gift_card_from_gan` | Retrieves detailed information about a gift card by its GAN (gift card account number) |
| **Get invoice** `square_get_invoice` | Retrieves detailed information about a specific Square invoice by its ID |
| **Get loyalty account** `square_get_loyalty_account` | Retrieve detailed information about a specific Square loyalty account by ID |
| **Get merchant** `square_get_merchant` | Retrieve detailed information about a specific Square merchant by ID |
| **Get online checkout location settings** `square_get_online_checkout_location_settings` | Retrieve location-level settings for Square online checkout |
| **Get refund** `square_get_refund` | Retrieves a specific payment refund by its unique ID from Square |
| **Get subscription** `square_get_subscription` | Retrieves detailed information about a specific Square customer subscription by its ID |
| **Get team member** `square_get_team_member` | Retrieve detailed information about a specific Square team member by ID |
| **List cards** `square_list_cards` | Retrieve cards on file associated with a Square account |
| **List channels** `square_list_channels` | List requested channels from Square |
| **List customer custom attribute definitions** `square_list_customer_custom_attribute_definitions` | List customer-related custom attribute definitions from Square |

## Example prompts

**Reconcile yesterday's sales**

> Run square_list_payments for my locations covering yesterday, group the payments by location, and tell me gross, refunds, and net for each. Flag any payment whose status is not COMPLETED. Do not change anything.

**Build a draft order**

> Use square_create_order to build an order for the items I list with quantities and prices, but do not submit it. Show me the full line-item breakdown and total before I confirm.

**Refund a payment**

> Find the payment for invoice 2026-0001 with square_list_payments or square_search_orders, tell me its amount and status, and prepare a square_create_refund for the full amount. Show me what you will refund and wait for my confirmation.

**Find a catalog item**

> Run square_search_catalog_objects for the item name I give you and return its SKU, price, and whether it is currently on the catalog. If it is not there, tell me the closest matches instead of guessing.

## What the 122 Square tools cover

The set grouped by business function, with the location_id dependency called out because it trips the most errors.

- **Payments and orders**: square_list_payments, square_search_orders, square_create_order, square_calculate_order, square_pay_order, square_create_refund, and payment links (square_retrieve_payment_link).
- **Catalog and inventory**: square_upsert_catalog_object and batch upserts, square_search_catalog_objects, square_retrieve_inventory_counts_batch, and square_create_batch_inventory_changes.
- **Customers and loyalty**: customer create, update, search, and bulk operations, customer groups and segments, gift cards, and loyalty accounts.
- **Disputes**: square_accept_dispute, square_create_dispute_evidence_file and text, square_list_dispute_evidence, and square_retrieve_dispute.
- **Locations and merchant**: square_get_current_merchant, square_list_locations, and square_retrieve_token_status for checking the grant's validity and scopes.
- **Team, subscriptions, and webhooks**: team member creation and updates, subscriptions, invoices, webhook subscriptions, and the webhook signature key tool.

## ClawLink vs. building it yourself

The alternative to ClawLink is usually manual OAuth app setup plus your own token handling, permission troubleshooting, and tool plumbing for Hermes Agent. That is fine if you want to build and maintain the integration yourself. Most teams just want Square working from chat.

| | Manual | ClawLink |
|---|---|---|
| **Connection flow** | Register a Square app, configure redirect URLs, manage consent details, and reconnect users when auth settings drift. | Users connect Square through the hosted browser flow and ClawLink keeps the token lifecycle out of your app code. |
| **Ongoing maintenance** | You own refresh logic, permission debugging, environment config, and every provider-specific edge case for Square. | ClawLink handles the repetitive integration plumbing so your team can focus on the workflow instead of the infrastructure. |
| **Agent usability** | You still need to expose the right Square actions to the runtime in a format your agent can reliably use. | 122 tools for Square are already exposed through ClawLink, so the agent can read and act from chat immediately. |

## ClawLink vs. Composio

Composio also exposes Square to AI agents. It is developer infrastructure: Python and TypeScript SDKs, an MCP server, and a catalog past 1,000 apps, aimed at teams shipping agent products. ClawLink is built for Hermes Agent users instead. You install the plugin once, connect Square in the browser, and the 122 tools above work from chat. There is no SDK, no config file, and no API key handling. Choosing between them? Read the full [Composio alternatives](https://claw-link.dev/hub/composio-alternatives) comparison.

### Hermes paired but still can't use Square
Pairing is a two-step handshake: run `hermes clawlink begin`, approve the link in your browser, then run `hermes clawlink finish`. If you ran finish before approving, or the approval link expired, run `hermes clawlink begin` again to get a fresh link. Confirm the plugin was installed with `--enable`, then verify with `hermes clawlink test`.

### Connection succeeds but no tools appear
Reconnect Square from the dashboard, then start a fresh chat if the runtime still has the old tool catalog loaded.

### "Tool schema not loaded yet" error when calling Square tools
Square tool schemas load on demand the first time a tool runs and are cached after that, so this error usually clears on its own: wait a few seconds and retry the same request. If every Square call keeps failing with it in a fresh chat, reconnect from the dashboard, and contact support if it still persists — that pattern points to a configuration problem on our side, not something you can fix by reconnecting again.

### Square returns 403 or "permission denied" on one action while others work
Two usual causes. The connected account may not have access to the specific workspace, inbox, store, or project in the request — check that first. If access looks right, the agent may have sent a placeholder value (like "YOUR_ID" or an example id from documentation) instead of a real one: ask it to run a list or search tool first, then retry the action with a real id from those results. Most failures at this stage are one of these two, not ClawLink bugs.

### Square API 401 invalid token on a connected account
The standard advice assumes a personal access token you regenerate in the developer dashboard, and that is the wrong fix here, because the connection is an OAuth grant with no token you own. An expired or revoked grant produces a 401 while the dashboard still shows the connection as connected, and a grant whose scopes changed after a Square-side policy update behaves the same way. The toolset has the right diagnostic for this: square_retrieve_token_status reports token validity, expiration, and authorized scopes. If it confirms the grant is stale, the recovery is to reconnect Square from the ClawLink dashboard, which re-runs the consent flow and replaces the stored grant. A refund on a payment that Square has already cancelled produces a similar-looking error; check the payment state before assuming the connection broke.

### Square API 403 insufficient permissions
Most Square endpoints require a location_id, and a wrong or missing location is the most common way a 403 appears while other tools keep working: the connection is fine, the location is not. Get real ids from square_list_locations instead of letting the agent invent them. The second cause is scope: the OAuth grant carries the permissions approved at consent, and a tool that needs CUSTOMERS_WRITE or a payments scope the grant lacks will 403 on that call alone. Reconnect from the dashboard to re-run consent if you need a wider grant. The third is merchant state: a suspended or unverified seller account produces permission-shaped errors across the board, which is a Square-side check, not a connection fix.

### Square API rate limit exceeded
Square does not publish fixed rate limits; limits are dynamic, applied per endpoint and per location, and can change without notice. What that means in practice is a bursty agent (a list_payments loop across months, or create_order calls in a tight loop) can trip a 429 response that has no documented number behind it. The response carries the instruction to slow down, and the fix is exponential backoff, not reconnecting: reconnect changes nothing, because the limit is on Square's side. Shape the work instead: one square_search_orders call with a date range beats thirty list calls, and batch catalog reads into square_search_catalog_objects.

### Square MCP tool not found
Search results blame a local MCP registry: malformed configuration in Cursor, a null-field bug in Claude Desktop, formatting errors in a config file. There is no local MCP registry in this setup, so those fixes do not apply. Here, Square tool schemas load on demand the first time a tool runs, and a call in a fresh chat can arrive before the catalog is hydrated; retrying once resolves it. If the same name fails twice, the name is wrong rather than missing, and the error message lists the closest real tools. Reconnect from the dashboard if every Square call keeps failing in a fresh chat.

### OAuth finished in the browser but the account is still missing
Try reconnecting Square and complete the consent flow in the same browser session. Partial OAuth approvals or switching accounts mid-flow can leave the connection incomplete.

### Is there a Hermes Agent Square integration?
Yes. ClawLink is the fastest way to connect Hermes to Square: link your Square account once in the browser and Hermes Agent can call the Square API through 122 ready-made tools — no custom code or token handling.

### How do I connect Square to Hermes with ClawLink?
Install the plugin with `hermes plugins install ClawLink-HQ/hermes-plugin --enable`, then pair once: run `hermes clawlink begin`, approve the link in your browser, and run `hermes clawlink finish`. Connect Square in the dashboard and Hermes can use it from the next message — no config files or API keys to manage.

### How long does it take to connect Square to Hermes Agent?
About two minutes. Sign in, click Connect next to Square in the dashboard, authenticate, and Hermes Agent can use it from the next chat message.

### Why use ClawLink instead of wiring Square up myself?
The alternative to ClawLink is usually manual OAuth app setup plus your own token handling, permission troubleshooting, and tool plumbing for Hermes Agent. That is fine if you want to build and maintain the integration yourself. Most teams just want Square working from chat.

### Do I need a Square developer app or access token?
No. The official Square MCP server requires a Square developer app, sandbox credentials, and access token management, which is what the "best square mcp server" answers teach. This connection goes through Square's OAuth flow against your seller account: you approve it in the browser, and no developer dashboard is involved. The agent inherits what your Square account can reach, the same way a user-approved integration would.

### Does this connect to my sandbox or my live store?
Your live seller account. Sandbox credentials belong to a developer application and a specific sandbox location, and this flow creates neither, so there is no sandbox environment to point at. Everything the agent reads or writes, from square_list_payments to square_create_order, is against the account you approved.

### What can the agent actually do with Square?
The read side is reconciliation and operations: square_list_payments by location and time range, square_search_orders across locations, customer profiles, catalog objects, inventory counts, and locations (square_list_locations returns the location ids the other tools need). The write side is real money movement: square_create_order builds orders, square_create_refund returns funds for a completed payment, and square_accept_dispute and evidence tools sit on top of disputes. Ask for reads and drafts first; approve refunds and order submissions before they go.

### Is it safe to connect Square to an AI agent?
The engines answer this with enterprise security vendor copy about least privilege and human approval, and none of them mention the model this product uses: connect in the browser, revoke in the dashboard. The grant is visible in your Square account, revocation is immediate, and there is no token file on the machine running your agent. The part the vendors are right about is human approval on writes, and the money-moving tools above are exactly where that applies. An agent that drafts a refund and waits for your confirmation behaves like a cautious teammate; an agent that executes refunds unprompted is a liability no connection model fixes.

### Hermes paired but still can't use Square
Pairing is a two-step handshake: run `hermes clawlink begin`, approve the link in your browser, then run `hermes clawlink finish`. If you ran finish before approving, or the approval link expired, run `hermes clawlink begin` again to get a fresh link. Confirm the plugin was installed with `--enable`, then verify with `hermes clawlink test`.

## Related

- [Zoho Books](https://claw-link.dev/hermes/zoho-books) — Organize finances, invoices, bills, and accounting
- [Hermes Zoho Invoice integration](https://claw-link.dev/hermes/zoho-invoice) — Create and send invoices, track payments, and manage billing
- [Connect Sevdesk](https://claw-link.dev/hermes/sevdesk) — sevDesk is an online accounting software designed for small businesses and freelancers, offering features like invoicing, expense management, and financial reporting.