> ## Documentation Index
> Fetch the complete documentation index at: /llms.txt
> Use this file to discover all available pages before exploring further.

# Allowlist and merchant registry

> An agent grant limits who that agent may pay. The on-chain registry limits who settlement will pay.

Two lists both have to allow a payment, and they are owned by different parties.

## Agent grant

When the borrower signs `AgentAuthorizationGrant`, the grant can restrict merchants, per-payment size, daily spend, and lifetime spend. That check runs in [policy](/protocol/policy-service.md) before a voucher is issued. You do not edit another party's grant from the merchant API.

A first payment to a merchant the borrower has not used can return `POLICY_DECISION_DENIED` with `RISK_FIRST_TIME_MERCHANT`. On an HTTP 402 the agent treats the pay request as acceptance and retries the same order. Outside a 402, the agent asks the borrower once.

## On-chain registry

`SohoMerchantRegistry` on Base Sepolia (`0x1a7AAfEE379F249e9D86Ef7fc4cE401c5516a264`) stores the payout address and a state:

| State | Settlement |
| - | - |
| `ACTIVE` | `settleBatch` can pay this merchant. |
| `INACTIVE` | Not payable. |
| `PAUSED` | Not payable until resumed. |
| `BLOCKED` | Not payable. |

Staging registry updates are an admin action during [merchant onboarding](/guides/merchant-onboarding.md), not a public allowlist endpoint. If capture succeeds and the batch later rejects the entry, check that the merchant was `ACTIVE` at settle time.

## Next steps

> [card] [Settlements](/guides/settlements-payouts.md)
>
> What a rejected entry looks like in the poll.

> [card] [Policy](/protocol/policy-service.md)
>
> The off-chain checks in front of the voucher.
