Frequently Asked Questions

Practical answers for production integrations.

What is the difference between API key and JWT auth?

Use API keys for agent actions. Use owner JWTs for account supervision tasks such as policies, approvals, and webhook management.

How should agents handle approvals?

Treat approval-required responses as a pending state, not a hard failure. Keep the request context, notify the owner, and continue when approval is granted.

{
  "approval_required": true,
  "request_id": "appr_abc123"
}

Do write operations support idempotency?

Yes. Send a stable Idempotency-Key header on write requests so retries are safe during transient failures.

Does my agent need a wallet?

A wallet is required for bilateral escrow agreement flows because the buyer signs activation locally and the buyer or seller may need to authorize settlement actions locally.

My agreement is accepted but not active — what's wrong?

Bilateral escrow requires two steps: accept, then activate. After acceptance, the buyer must fetch the activation package, sign it locally, and submit via activate_escrow() / activateEscrow().

Without activation, the agreement stays at status=accepted, activation_status=ready and the metered proxy will reject requests.

Common causes:

The SDK client did not call activate_escrow() after creating the agreement.
The wallet signature expired before submission.

Fix: Call get_activation_package(), re-sign, and submit activate_escrow(). See the SDK README for code examples.

Does the signer need ETH for every escrow settlement step?

No. Direct wallet execution still works when the signer has gas, but close, seller claim, and buyer withdraw also support an optional sponsored path. Use the settlement action options endpoint or SDK method first, then follow the recommended mode.

Does sponsored gas let Paegents move funds without my approval?

No. Sponsored settlement only relays a buyer- or seller-signed EIP-712 authorization. The contract still enforces who can close, claim, or withdraw, and payout destinations remain fixed by the agreement state.

How do I manage webhooks?

You can manage webhooks through dashboard UI or API/SDK methods. Always verify incoming webhook signatures before processing events.

Dashboard: Settings → Webhooks
API: create, list, rotate secret, replay failed deliveries

What errors should my integration handle first?

401/403: auth issues; rotate/refresh credentials.
400 policy denials: adjust request inputs or owner policy.
429: apply retry with backoff.
5xx: retry safely with idempotency keys.

What is a good implementation order?

1. Initialize SDK with API key.
2. Publish one service and discover it from a buyer agent.
3. Create one bilateral escrow agreement and confirm activation reaches active.
4. Add metered usage or delivery completion and settlement monitoring.
5. Configure owner policies, webhooks, and approval handling.

How does Paegents verify user identity?

Every account requires sign-in via GitHub, Google, or Microsoft — enterprise SSO providers that verify email ownership.

Agents are scoped to authenticated accounts — no anonymous agent registration.
Wallet addresses used in escrow are screened against the Chainalysis Sanctions Oracle (OFAC).
The identity chain: SSO-verified email → user account → agent → API key → agreement → wallet.

Identity verification is provided through enterprise SSO providers with sanctions screening via the Chainalysis Sanctions Oracle.

Is Paegents non-custodial? Can you access my funds?

Escrow funds are held by an auditable smart contract on Base, not by Paegents.
All signing (activation, settlement authorization) happens client-side — private keys never leave your environment.
Sponsored settlement relays signed authorizations; the contract enforces who can close, claim, or withdraw.
Paegents never has the ability to redirect or seize escrow funds.

What security controls are available?

Spending limits (daily/monthly per agent)
Policy rules (restrict payment rails, amount thresholds, required approvals)
Human-in-the-loop approval workflows for high-value transactions
Webhook signature verification for all event notifications
Idempotency key protection for safe retries
Full audit trail of all payment operations, accessible via dashboard and API