Unhold: PayPal Sentinel

Pick the work you came to do: Unhold starts from the person. Pick a role—Owner, Fulfilment, Support, Admin, or Guided tour.
Owner work queue: Highlights held totals ($5,235), releasable cash ($1,451), account health (53/100 At risk), and agent actions.
Held money & waterfall: Explains hold causes in plain English (2.85× surge, missing tracking) with weekly cash projections.
Every hold in AG Grid: 106 holds with tracking numbers, state chips, plain-English filtering, and KERNEL carrier-check buttons.
Carrier parcels matched to orders: 3-tier matcher pairs manifests to PayPal orders with confidence scores and clear rationale.
The agent proposes; a person decides: Human-in-the-loop plan review with Slack approval integration via Zapier.
Release timeline: Visual calendar comparing PayPal 21-day releases (orange) against expedited ~24h post-delivery releases (green).
Cash goal forecaster: 2,000-run simulation planning minimal actions to reach target working capital with >90% confidence.
Payment Guard anti-scam check: Verifies notices against PayPal API, blocking spoofed emails and fake payments with "Do not ship".

Inspiration

PayPal's risk and hold system is one of the reasons buyers trust PayPal and merchants get paid safely. When a small business sees a sudden sales surge, such as a 2.9x volume spike during a product launch or holiday rush, PayPal may hold incoming funds for up to 21 days. That is a sensible safeguard: rapid, unfamiliar growth is exactly when buyers and the platform need protection.

PayPal also gives merchants a clear path to earlier release: add tracking, and funds can be released about 24 hours after confirmed delivery. Many growing merchants never use it. They fulfill orders through Shopify, WooCommerce, or their own shipping tools and never sync tracking back to PayPal. We call this "The Untracked Orders Trap": goods are shipped and delivered, but PayPal never receives the signal it is designed to act on, so cash stays in pending_balance.

Merchants also face fake "Payment Received" phishing emails, in which scammers impersonate PayPal to trick sellers into shipping unpaid goods. These scams hurt merchants and erode trust in the PayPal brand.

We built Unhold: PayPal Sentinel to help merchants work with PayPal's protections rather than around them. It combines PayPal's REST APIs (Balances, Orders v2 Tracking, Disputes) with a supervised multi-agent team and ten sponsor tools (AG Grid Enterprise, Astropods, Zapier, Elastic, KERNEL, Channel3, Bryntum, Render, Postman, APIMatic). Unhold detects held funds, verifies that each transaction is real, and attaches carrier tracking so PayPal's standard post-delivery release can take effect, often 12–20 days sooner.

The outcome is a win for everyone:

Merchants get earlier access to their own money.
Buyers get verified delivery.
PayPal sees fewer "Item Not Received" disputes, lower loss exposure, and healthier, longer-retained merchants.

What it does

Unhold: PayPal Sentinel is a supervised multi-agent assistant and merchant cockpit. It helps PayPal merchants keep their accounts in good standing, protect themselves from fraud, and receive held funds through PayPal's existing release mechanisms.

1. Supervised Multi-Agent Team (Supervisor Pattern)

Unhold runs a deterministic loop: perceive → reason → plan → ask → human approves → act → verify → learn. A Supervisor Agent coordinates three specialized agents:

Cash-flow Agent turns delivered orders into the signal PayPal's release process expects:
- It scans storefront manifests and matches carrier tracking numbers (UPS, FedEx, USPS) to PayPal Order IDs.
- It prepares batch upload plans.
- It posts tracking to PayPal's Orders v2 Tracking API (POST /v2/checkout/orders/{id}/track).
Payment Guard Agent verifies transaction IDs against PayPal's REST records before shipment. This catches spoofed "Payment Received" emails (Phantom Orders). It also flags pricing anomalies using Channel3 product graphs.
Buyer Assurance Agent reviews buyer disputes, compiles delivery evidence, and neutralizes prompt-injection attempts in buyer messages.

2. Human-in-the-Loop Safety: "Model Explains, Code Decides"

In financial operations, the AI model explains and deterministic code decides. The policy engine limits what the agents can propose and rejects any LLM output that contains unverified figures. No tracking is posted to PayPal without explicit human approval, given through signed, single-use links in Slack or the merchant cockpit.

3. Role-Based AG Studio Cockpit

Built on AG Grid Enterprise, the cockpit shows each operational role its own screens and work queues:

Owner: cash goals, pending approvals, and expected release timelines.
Fulfillment: parcel matching, untracked paid orders, and tracking uploads.
Support: dispute replies, buyer assurance alerts, and Payment Guard anti-scam checks.
Admin: agent runs, system logs, error recovery, and the audit chain.
Guided Tour: a 7-step walkthrough of the full loop that clearly labels which steps are real and which are simulated in the sandbox.
"Ask the Grid": natural-language queries that update the live grid. Example: "Which held orders have verified delivery scans ready for tracking upload?"

4. Tamper-Evident SHA-256 Audit Ledger

Every agent perception, reasoning step, approval, and API payload is written to an append-only, SHA-256 hash-chained log (audit.jsonl). Users can verify the chain directly from the UI.

How we built it

Unhold is a TypeScript/Node.js stack integrated with the PayPal Sandbox and ten sponsor tools.

PayPal Platform APIs:
- Orders v2 Tracking API (POST /v2/checkout/orders/{id}/track): batch-uploads tracking numbers, carrier codes, and item-level SKUs so orders qualify for PayPal's post-delivery release.
- Balances API (GET /v1/reporting/balances): reads pending_balance to identify held transactions.
- Captures & Webhooks APIs: verify live order status to filter phishing attempts and receive delivery events.
Sponsor Tool Integrations:
- AG Grid Enterprise: powers the role-based cockpit grids, with row grouping, sparklines, master-detail views, and "Ask the Grid."
- Astropods: packages the agent team as a blueprint (astropods.yml, AGENT.md, Dockerfile.astropods) with OpenTelemetry spans (gen_ai.* / unhold.*).
- Zapier: sends approval requests to Slack through catch hooks and Zapier MCP, ingests carrier manifests, and triggers agent runs (/api/manifests/ingest).
- Elastic: provides hybrid semantic and keyword search across holds, audit records, disputes, and evidence.
- KERNEL: runs cloud browser automation to confirm delivery status on carrier tracking pages.
- Channel3: performs product-graph price lookups to catch pricing anomalies.
- Bryntum: shows expected release schedules on an interactive timeline (public/timeline.js).
- Render: hosts the services and runs 6-hourly background sweeps via render.yaml.
- Postman: provides a complete, tested API collection (postman_collection.json).
- APIMatic: imports the Orders v2 spec for type-safe payload generation.
Data & Observability:
- Supabase Postgres stores operational ledgers, agent run history, and structured Pino JSON logs.
- Prometheus endpoints are exposed at /metrics, /healthz, and /readyz.

Challenges we ran into

Simulating holds responsibly
- Challenge: As expected for a test environment, the PayPal Sandbox does not reproduce production risk holds.
- Solution: We ran real sandbox tracking uploads (POST /v2/checkout/orders/{id}/track) on 4 demo orders paid by a US sandbox buyer. We paired them with a seeded historical ledger of 106 holds totaling $5,235.24, which the UI clearly labels "Simulated seller history."
Prompt injection and financial safety
- Challenge: Malicious buyers could embed instructions in dispute messages to manipulate the AI agents.
- Solution: Deterministic boundary code validates every model output against raw tool results. Any unverified amount or unauthorized action is rejected and replaced with a safe fallback.
Regional sandbox account pairing
- Challenge: Sandbox buyers must match the seller's region. For example, an Indian buyer account cannot pay a US seller account.
- Solution: We wrote seeding scripts (npm run seed:live -- 4) that pair regions correctly when generating and capturing sandbox orders.
Multi-agent tracing and hermetic testing
- Challenge: State had to stay consistent across asynchronous agent runs, human approvals, and webhooks, with full observability.
- Solution: We wrote 71 hermetic unit tests against in-memory Postgres and 23 end-to-end browser tests that cover every role, grid interaction, and approval link.

Accomplishments that we're proud of

Faster access to merchant cash through PayPal's own process: In a simulated surge dataset of $5,235 in held funds, Unhold showed $1,869.00 becoming eligible about 12 days sooner via PayPal's standard post-delivery release.
Stronger Seller Protection readiness: Unhold attaches valid tracking before dispute windows open, helping orders meet the tracking requirement for PayPal Seller Protection against "Item Not Received" claims.
No unapproved financial actions: Every tracking upload and API action required explicit human approval through signed tokens.
Ten sponsor tools in one product: AG Grid Enterprise, Astropods, Zapier, Elastic, KERNEL, Channel3, Bryntum, Render, Postman, and APIMatic work together as one cohesive system.
Production-grade engineering: 71 unit tests, 23 browser tests, structured logging, Prometheus metrics, and a SHA-256 audit chain.

What we learned

PayPal's holds are a feature, not a bug. The most effective way to help merchants was to supply the signals PayPal's system is already designed to trust, rather than trying to bypass it.
"Model explains, code decides" is essential. When AI agents touch live payment rails, deterministic guardrails and human approval are mandatory.
Tracking is a high-leverage integration. Orders v2 tracking connects fulfillment to PayPal's post-delivery release and Seller Protection, and it is underused by small merchants.
Observability makes agents debuggable. OpenTelemetry spans across the supervisor and its agents gave us the visibility to trace multi-step reasoning end to end.

What's next for Unhold: PayPal Sentinel

Storefront and ERP integrations: one-click apps for Shopify, WooCommerce, Magento, and QuickBooks that sync shipping manifests in real time.
Digital goods and services: support for PayPal's Delayed Disbursement option (disbursement_mode: DELAYED), releasing funds when download or service milestones are confirmed.
Dispute evidence packages: let the Buyer Assurance Agent assemble complete evidence (carrier delivery scans, order records, buyer communications) for submission through PayPal's Disputes API (/v1/customer/disputes).
Merchant health insights: give merchants a rolling view of fulfillment and tracking reliability, with guidance on keeping their accounts in good standing. Where merchants consent, this could become a trusted signal for PayPal's risk teams.