Allowlist Management

Your allowlist is the set of agents allowed to pay you. No agent — regardless of its credit line — can settle a payment to your merchant account unless it’s on this list. This guide covers managing the allowlist via API and dashboard, and explains how enforcement actually works.

Add an agent

Add an agent by its agt_ ID. You’ll typically get this ID from the operator integrating with you, or from your own agent setup if you run both sides.

curl -X POST https://api-sandbox.sohopay.xyz/v1/merchants/mch_4a2b9c31/allowlist \
  -H "Authorization: Bearer $SOHOPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: allowlist-agt_7d1e5b2f-v1" \
  -d '{
    "agent_id": "agt_7d1e5b2f",
    "label": "acme-shopping-agent"
  }'

import { SohoPay } from "@sohopay/sdk";

const sohopay = new SohoPay({ apiKey: process.env.SOHOPAY_API_KEY });

const entry = await sohopay.merchants.allowlist.add("mch_4a2b9c31", {
  agentId: "agt_7d1e5b2f",
  label: "acme-shopping-agent",
});

console.log(entry.status, entry.onchainTx);

from sohopay import SohoPay

sohopay = SohoPay(api_key=os.environ["SOHOPAY_API_KEY"])

entry = sohopay.merchants.allowlist.add(
    "mch_4a2b9c31",
    agent_id="agt_7d1e5b2f",
    label="acme-shopping-agent",
)

print(entry.status, entry.onchain_tx)

The response includes the on-chain transaction that wrote the entry:

Response

{
  "merchant_id": "mch_4a2b9c31",
  "agent_id": "agt_7d1e5b2f",
  "label": "acme-shopping-agent",
  "status": "active",
  "onchain_tx": "0x2f8a...c41d",
  "added_at": "2026-08-22T11:04:18Z"
}

Allowlist changes are written on-chain and take effect within ~1 block (about 2 seconds on Base). A payment submitted in that window may still be evaluated against the old list — retry once if timing matters in a test.

Remove an agent

Removal is immediate and also written on-chain. Any in-flight orders from that agent will fail at settlement.

curl -X DELETE https://api-sandbox.sohopay.xyz/v1/merchants/mch_4a2b9c31/allowlist/agt_7d1e5b2f \
  -H "Authorization: Bearer $SOHOPAY_API_KEY"

await sohopay.merchants.allowlist.remove("mch_4a2b9c31", "agt_7d1e5b2f");

sohopay.merchants.allowlist.remove("mch_4a2b9c31", "agt_7d1e5b2f")

Response

{
  "merchant_id": "mch_4a2b9c31",
  "agent_id": "agt_7d1e5b2f",
  "status": "removed",
  "onchain_tx": "0x9b3e...77a2",
  "removed_at": "2026-08-22T11:20:41Z"
}

List allowlisted agents

curl https://api-sandbox.sohopay.xyz/v1/merchants/mch_4a2b9c31/allowlist \
  -H "Authorization: Bearer $SOHOPAY_API_KEY"

const entries = await sohopay.merchants.allowlist.list("mch_4a2b9c31");

entries = sohopay.merchants.allowlist.list("mch_4a2b9c31")

Response

{
  "data": [
    {
      "agent_id": "agt_7d1e5b2f",
      "label": "acme-shopping-agent",
      "status": "active",
      "added_at": "2026-08-22T11:04:18Z"
    }
  ],
  "has_more": false
}

Dashboard alternative

Everything above is also available in the dashboard under Agents → Allowlist: search agents by ID or label, add or remove them with a click, and see the on-chain transaction for each change. The dashboard is a convenience layer over the same API — there is no separate permission model.

How enforcement works on-chain

The allowlist is not an API-layer filter. Every settlement requires a 2-of-3 MPC co-signature from the Policy Service, and the allowlist check reads on-chain state. If the paying agent is not on your list, the Policy Service refuses to co-sign, so the USDC transfer can never be constructed — the payment fails with:

403 AGENT_NOT_ALLOWLISTED

{
  "error": {
    "code": "AGENT_NOT_ALLOWLISTED",
    "message": "Agent agt_7d1e5b2f is not on the allowlist for merchant mch_4a2b9c31.",
    "request_id": "req_c91f2ab0"
  }
}

This means a compromised API server, a buggy operator integration, or a rogue agent still cannot move funds to you outside your allowlist. The guarantee is cryptographic, not procedural.

Error cases

Error	Status	Cause and fix
`INVALID_AGENT`	400	The `agent_id` doesn’t exist or is malformed. Confirm the `agt_` ID with the operator.
`AGENT_REVOKED`	403	The agent exists but its operator revoked it. It cannot be allowlisted; ask the operator for the replacement agent.
`AGENT_NOT_ALLOWLISTED`	403	Returned on payment, not on allowlist calls — the agent tried to pay you before being added.
`RATE_LIMITED`	429	Bulk-adding too fast. Honor the `Retry-After` header.

Adding an agent that’s already on the list returns the existing entry with 200 — the operation is idempotent, and sending an Idempotency-Key on POSTs makes retries safe. Full envelope details are in the error reference.

Test it

Add a sandbox agent and confirm the response contains an onchain_tx hash
View the entry on Sepolia Basescan using that hash
Submit a payment from a non-allowlisted agent and confirm you get 403 AGENT_NOT_ALLOWLISTED
Remove the agent, retry the payment, and confirm it now fails too
Confirm the dashboard Agents → Allowlist view matches GET /merchants/{id}/allowlist

Next steps

Settlements & Payouts

Where the money lands once allowlisted agents start paying.

Policy Service

The co-signing checks behind allowlist enforcement.

Error Reference

Every error code, status, and the standard envelope.

Getting Started

Merchant Integration

Agent Wallet Setup

Payment Flow

Protocol & Standards

Compliance & Risk

Operational Dashboards

Allowlist Management

Add an agent

Remove an agent

List allowlisted agents

Dashboard alternative

How enforcement works on-chain

Error cases

Test it

Next steps

Settlements & Payouts

Policy Service

Error Reference

​Add an agent

​Remove an agent

​List allowlisted agents

​Dashboard alternative

​How enforcement works on-chain

​Error cases

​Test it

​Next steps

Settlements & Payouts

Policy Service

Error Reference

Add an agent

Remove an agent

List allowlisted agents

Dashboard alternative

How enforcement works on-chain

Error cases

Test it

Next steps