Service twin · API + UI
Trolley
Test payout agents that onboard recipients, manage compliance, and coordinate global payment workflows.
API + UIdocs-transcribedREST · MCP · CLI
Terminal
$ uv tool install --with "blobfish-sdk @ https://blobfish.ai/sdk/blobfish_sdk-0.6.2-py3-none-any.whl" "blobfish-cli @ https://blobfish.ai/sdk/blobfish_cli-0.1.13-py3-none-any.whl"
$ blobfish login
$ blobfish twin-runs create --twins trolley --ttl 60 --waitWhat’s inside
A deterministic, seeded, resettable replica: every operation below executes real state transitions against the twin’s own SQLite state — reads are hash-invariant, writes produce inspectable diffs, and reset restores the seed baseline.
Seeded entities
| Entity | Table | Fields | About |
|---|---|---|---|
| recipient | recipients | 8 | Payee (creator, freelancer, or vendor business) onboarded to receive global payouts. |
| recipient_account | recipient_accounts | 9 | Payout destination (bank account or PayPal wallet) attached to a recipient. |
| batch | batches | 7 | Payout batch that groups payments: assembled while open, then sent for processing until complete. |
| payment | payments | 8 | Single payout to a recipient inside a batch, tracked from pending through processing to settlement, failure, or bank return. |
| tax_form | tax_forms | 7 | Tax form / compliance record (W-9, W-8BEN) a recipient completes and the payer team reviews before payouts clear. |
| invoice | invoices | 8 | Receivable a recipient has billed for, settled in full or in part through payout batches. |
| offline_payment | offline_payments | 8 | Payment recorded for bookkeeping that settled outside Trolley (wire, check, or a legacy system). |
| balance | balances | 6 | Merchant funding balance available for payouts, per provider and currency. |
| verification | verifications | 7 | Compliance verification (identity, address, bank account, tax) gating a recipient's payout eligibility. |
| webhook_subscription | webhook_subscriptions | 6 | Webhook endpoint registration receiving payout, recipient, and compliance event notifications. |
Guarded lifecycles
These state machines are enforced, not decorative: an action whose from state doesn’t match is rejected the way the production service rejects it.
batch.status
open → processing → complete
start_processing: open → processingend_processing: processing → complete
payment.status
pending → processing → processed → failed → returned
mark_processed: processing → processedmark_failed: processing → failed
tax_form.status
incomplete → submitted → reviewed → voided
submit: incomplete → submittedreview: submitted → reviewed
invoice.status
open → partially-paid → paid → voided
pay: open|partially-paid → paidvoid: open|partially-paid → voided
verification.status
pending → submitted → approved → rejected
submit: pending → submittedapprove: submitted → approvedreject: submitted → rejected
Three surfaces, one state
Mount Trolley in a twin environment and the same seeded state serves vendor-shaped REST operations, an MCP endpoint for tool calling, and a generated bf-twin CLI — with copy-on-write sessions per rollout and a one-call reset to the seed baseline. Prefer raw HTTP? The same create works with curl:
API
$ curl -sS -X POST https://blobfish.ai/api/v1/twin/environments \
-H "X-API-Key: $BLOBFISH_API_KEY" -H "Content-Type: application/json" \
-d '{"services":["trolley"],"ttl_minutes":60}'Known limitations
- transcribed from https://docs.trolley.com/api; parameter and response schemas simplified
- nested recipient sub-resources (accounts, tax forms, verifications) flattened to top-level collections addressed by recipient_id filters; invoice payments, offline payments, and merchant balances modeled as top-level collections; asynchronous batch and payment processing modeled as explicit actions
- synthetic seeded values