Passwordless escrow for buyers and sellers. Create a deal, verify both inboxes by email OTP, fund with PayPal, then track dispatch → delivery → inspection → payout.
Three interfaces, one backend: the manual web forms, the website AI assistant (text + voice), and the WhatsApp AI assistant (text + voice notes) all run on the same escrow engine, the same validation, and the same money rules.
Built with Django + SQLite (local) / Postgres (prod) + PayPal + Termii + any OpenAI-compatible chat model (Modal shared endpoint by default) + Meta Model API (voice).
- Create, creator sets title, amount, counterparty email, role (buyer/seller), inspection days, and who pays the service fee. The draft is assembled by hand, by the AI chat, or by voice.
- Verify creator, a 6-digit email OTP proves the creator's inbox. The escrow becomes
awaiting_counterpartyand the counterparty is emailed a join link with the code prefilled. - Counterparty joins, they open the join link, prove their own inbox with an OTP, and accept the terms. The creator is notified instantly (WhatsApp push when linked, live webchat message if their chat is open, dashboard panel) and the escrow moves to
awaiting_funding. - Fund, buyer pays via PayPal from the dashboard button or from a payment link the AI fetches in chat. Webhook + callback fallback confirm against expected amount, currency, and reference. Pay Later works out of the box where PayPal offers it (buyer splits payments, seller is still funded in full); use a $30+ escrow to see the option.
- Dispatch, seller confirms dispatch in chat ("dispatched") or dashboard →
in_transit. Buyer is notified. - Receipt + inspection, buyer confirms receipt → inspection window starts (default 3 days, auto-releases via the
auto_release_escrowworker when eligible). Both sides are notified with the deadline. - Release / dispute, buyer says "release" in chat or clicks release → PayPal Payout to the seller's PayPal email. Either party can dispute instead; disputes freeze everything until ops resolves in admin.
- Done, seller and buyer both get payout confirmation.
State machine (escrow/models.py::EscrowContract.TRANSITIONS):
pending_verification → awaiting_counterparty → awaiting_funding → awaiting_dispatch
→ in_transit → in_inspection → pending_payout → completed
(disputed / cancelled reachable from funded states)
Money rules: amounts stored as decimals, charged in cents; tiered USD service fee (1.50 / 2.00 / 2.50 / 5.00 / 10.00 by band); buyer pays checkout total, seller receives net terms; every funding confirmation and payout is idempotent (conditional updates, single provider reference, uncertain parking on timeouts, never a blind retry).
- Manual web,
/create/,/join/,/escrow/<code>/detail with HTMX live panel (15s poll), My Escrow lookup by email+OTP, seller PayPal vault (email masked until funding). - Website AI assistant,
/assistant/chat (also embedded on/). Text, mic button (MediaRecorder → Muse transcription → normal agent turn), pending-action panel ("reply yes or discard"), New chat button, typeddiscardto drop a proposal. Bare 6-digit messages are treated as OTPs, never sent to the model. - WhatsApp AI assistant,
/webhooks/whatsapp/Cloud API webhook. Text and voice notes flow into the same bounded agent loop; email OTP verification binds the sender number to a verified identity (the number itself is never identity). Non-text messages get a gentle nudge back to text/voice.
The AI handles the whole arc conversationally: draft → confirm → code → join nudge → payment link → dispatch/receipt confirmations → release → payout confirmation. Lifecycle updates are pushed to WhatsApp and into the other party's open webchat (about 10 second poll) at every handoff.
- Python 3.14, Django (templates + HTMX, no separate frontend)
- Gunicorn + WhiteNoise,
dj-database-url - PayPal (Orders + Payouts + refunds), Termii (email OTP), SMTP/email (counterparty invites)
- Hold-to-speak voice notes on web and WhatsApp; cancelled or sub-second taps are discarded, never transcribed
- Any OpenAI-compatible chat model (served on Modal in this deployment), Meta Muse Voice Transcribe (STT)
- SQLite locally, managed Postgres when
DJANGO_DEBUG=False - Timezone:
Africa/Lagos
You need Python 3.13 or newer (the project runtime is Python 3.14), Git, and an AI inference key if you want to test the AI assistant. Point INFERENCE_* at any OpenAI-compatible endpoint (a Modal shared endpoint or self-hosted vLLM). For the quickest evaluation, use Demo mode below. It needs no Termii or PayPal keys.
# 1. Clone + venv
git clone https://github.com/Dekantiok/LocktransAI.git
cd LocktransAI
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install -r requirements.txt
# 2. Configure
cp .env.example .env
# For judging, paste the Demo mode .env shown in the next section.
# For real integrations, fill in PAYPAL_CLIENT_ID/SECRET, TERMII_*, and the other keys.
# 3. Migrate + run (migrate is mandatory on every fresh checkout)
python manage.py migrate
python manage.py runserverOpen http://127.0.0.1:8000/ and check:
- The home page loads with a blue Demo mode banner when
DEMO_MODE=True. - The chat answers. If it says the AI is unavailable, no inference key is configured (
INFERENCE_API_KEY) or the endpoint is unreachable in.env. Restart the server after changing.env. - The full judge script in Demo mode below completes and the escrow ends as
completed.
Useful commands:
python manage.py test # full suite incl. UI SmokeTest guardrails
python manage.py auto_release_escrow # release expired inspections (Procfile worker)
python manage.py collectstatic # prod static build
python manage.py flush # wipe local test data and start again (asks first)Demo mode lets you run the complete escrow circle locally with no Termii account and no PayPal account. Only those two integrations are simulated. The AI, voice transcription, escrow rules, confirmations, PayPal email checks, notifications, and audit trail all run for real.
Put this in .env, then restart runserver:
DJANGO_DEBUG=True
DJANGO_SECRET_KEY=local-dev-secret-change-me
DJANGO_ALLOWED_HOSTS=127.0.0.1,localhost
# The only keys you must supply yourself for AI and voice:
# Point at any OpenAI-compatible endpoint, e.g. a Modal shared endpoint:
INFERENCE_API_KEY=your-key-or-proxy-token
INFERENCE_BASE_URL=https://inference.us-west.modal.direct/v1
INFERENCE_MODEL=your-endpoint-hostname-or-model-id
MODEL_API_KEY=your-meta-model-api-key
# Demo switches. Leave every TERMII_* line blank or dummy.
# DEMO_SIMULATE_PAYMENTS=True (default) needs no PayPal account at all.
# Set it to False (with PAYPAL_* sandbox keys) for real PayPal checkout,
# capture, and payouts while OTPs stay stubbed to 123456.
DEMO_MODE=True
DEMO_OTP_CODE=123456
DEMO_SIMULATE_PAYMENTS=TrueNotes:
INFERENCE_*points the AI chat at any OpenAI-compatible endpoint. Without them the site still loads and the manual forms still work, but the assistant replies that it is temporarily unavailable.MODEL_API_KEYpowers voice notes only. Without it, typing works everywhere and voice asks you to type instead.- WhatsApp is optional for local judging. It needs a Meta WhatsApp app plus a public HTTPS tunnel (see Deployment). Skip it locally unless you are specifically scoring WhatsApp.
- Seller payouts go to a PayPal email saved on the vault; no bank resolution is needed. Judging always runs against real PayPal sandbox (approve with a sandbox buyer account, payouts land in sandbox).
DEMO_SIMULATE_PAYMENTS=Trueexists only for keyless local development — never for judging.
In Demo mode only OTP email delivery is stubbed. Money always moves for real:
| Demo mode | Still fully real |
|---|---|
OTP email delivery. Use code 123456 anywhere a verification code is asked. Wrong codes still fail. |
OTP verification logic, attempt limits, expiry, and identity binding |
| Nothing else. Funding goes through real PayPal sandbox checkout; payouts are real PayPal sandbox transfers. | Amount and currency checks, funding state change, seller notification, vault requirement, inspection rules, dispute freeze, release confirmation, real payout records |
| AI tools and confirmations, join and resume, dispatch and receipt, payout email saving, disputes, dashboard, admin | (all real) |
Use two separate browser sessions, because each party needs its own identity. Easiest: Browser A normal window for Person 1, Browser B private/incognito window for Person 2. Refreshing a chat starts it fresh on purpose. To resume, say "continue" plus the escrow code and verify again.
Use your real email addresses for identity — nothing is emailed, the universal code is 123456 everywhere. Tip: your sandbox emails (e.g. sb-xyz@business.example.com) work as identities too, since delivery is stubbed — then each role needs only one address for both verification and money. For money movement, bring your own PayPal sandbox accounts (live logins don't work on sandbox checkout) — free at developer.paypal.com (sign up, and test buyer + seller accounts are auto-provisioned under Testing Tools → Sandbox Accounts):
- Person 1 (buyer) approves payment logged in as their own sandbox buyer account.
- Person 2 (seller) saves their own sandbox PayPal email on the vault, then logs into that sandbox account to see the released payout land.
Person 1 (buyer), Browser A, home page chat:
- Type or hold the mic and say: "I want to buy a laptop for 500 dollars from seller@example.com. My email is buyer@example.com, I am the buyer."
- When the assistant shows the terms, reply: "yes".
- When it says a code was sent, type
123456. The escrow is created. Note the code, it looks likeLKTRaB3xK. Share it with Person 2.
Person 2 (seller), Browser B, home page chat:
- Say: "I want to join escrow LKTRaB3xK" (use the real code).
- Give your email: "my email is seller@example.com".
- When the code arrives in the story, type
123456. You are joined, and Person 1 is notified in their open chat within about 10 seconds.
Person 1 (buyer):
- Say: "fund LKTRaB3xK", then reply "yes" when asked. A real PayPal sandbox checkout opens — log in with the sandbox buyer account, approve, and you'll return automatically.
Person 2 (seller):
- Your chat is told the escrow is funded. Say: "I have shipped it", then confirm with "yes".
Person 1 (buyer):
- Say: "I received it", then confirm with "yes". Inspection starts. The seller is now asked for their PayPal payout email.
Person 2 (seller):
- Say: "My PayPal email is ", then confirm with "yes". The assistant confirms the payout email is saved and masked for the buyer. Check it matches the email you expect.
Person 1 (buyer):
- Say: "release LKTRaB3xK", then confirm with "yes". Both sides are told the seller was paid and the escrow is complete.
Optional checks while you are there:
- Swap roles and fee payer on a second run ("I am the seller", "the seller pays the fee") and repeat.
- Raise a dispute instead of releasing at step 11 and confirm the funds stay frozen.
- Try a wrong OTP such as
000000once and confirm it is rejected, then use123456. - Open
/escrow/<code>/or/admin/(create an admin user withpython manage.py createsuperuser) and confirm the dashboard and audit trail match what the chats said.
The WhatsApp assistant runs the same agent, escrow engine, and money rules as the website. A judge needs: a Meta developer account, a WhatsApp Business test number, and a public HTTPS URL for this server (Meta cannot reach localhost).
1. Expose this server publicly. In one terminal, keep the app running:
python manage.py runserver 127.0.0.1:8000In a second terminal, open a tunnel (any provider works):
cloudflared tunnel --url http://127.0.0.1:8000
# or: ngrok http 8000Copy the public https://... URL it prints, for example https://abc-123.trycloudflare.com.
2. Create a WhatsApp test app. In the Meta App Dashboard, create an app, add the WhatsApp product, and complete the test-number setup (Meta provides a test phone number and a test recipient setup). Keep the dashboard open.
3. Fill in the WhatsApp settings. In this project's .env:
WHATSAPP_ACCESS_TOKEN=<temporary token from the WhatsApp > API setup page>
WHATSAPP_PHONE_NUMBER_ID=<the test phone number ID>
WHATSAPP_WEBHOOK_VERIFY_TOKEN=<any random string you invent, e.g. locktrans-verify-123>
WHATSAPP_APP_SECRET=<app secret from App settings > Basic>
WHATSAPP_API_VERSION=v21.0Then restart the server so it picks them up.
4. Point Meta at this server. Back in the dashboard, under WhatsApp > Configuration, set the callback URL to:
https://<your-tunnel-host>/webhooks/whatsapp/
Set the verify token to the exact WHATSAPP_WEBHOOK_VERIFY_TOKEN value, click Verify and save, and subscribe the webhook to the messages field. A green checkmark means Meta reached this server.
5. Talk to the bot. From a phone with WhatsApp, message the test business number (you may need to add it via the dashboard's test setup first):
hi
The bot asks for your email address. Reply with an email you control, then reply with the OTP code. In Demo mode (DEMO_MODE=True) the code is 123456, same as the website, and the troubleshooting table below applies.
6. Run the same circle as the web judge script. Everything from the website script works here: describe the deal, confirm, paste the code, share the LKTR code with the other party, join from the second party's own chat, fund via the payment link, dispatch, confirm receipt, add the payout PayPal email, and release. Voice notes work too: hold the mic in WhatsApp and speak instead of typing. Differences from the web channel to expect:
- Replies arrive as WhatsApp messages, and lifecycle nudges (counterparty joined, funded, shipped, payout) arrive unprompted.
- There is no page to refresh: the conversation persists in WhatsApp, so verification and proposals carry over between sessions.
- If a message gets no reply, the server log shows the reason. Common causes: the tunnel expired (restart it and update the dashboard callback URL), the temporary access token expired (generate a new one on the API setup page), or the webhook subscription lost the
messagesfield.
7. When finished. Stop the tunnel and revert .env (or leave WhatsApp blank). Nothing about WhatsApp changes the escrow state machine: an escrow started on WhatsApp is visible and actionable from the website with the same rules.
python manage.py flush # wipes escrows, chats, OTPs, and vaults in the local DBThen reload both browsers. There is no seed data to restore; the judge script above creates everything it needs.
| Symptom | Fix |
|---|---|
no such column: agent_aiconversation.pending_email or any no such column error |
Run python manage.py migrate, then restart the server. This is the most common fresh-checkout hiccup. |
| Chat says the AI assistant is temporarily unavailable | No inference key set (INFERENCE_API_KEY) or the endpoint is unreachable. Set the three INFERENCE_* values in .env and restart runserver. Manual forms still work without it. |
| Voice says transcription is not configured, or asks you to type | MODEL_API_KEY is missing. Voice also needs Chrome or Edge on http://127.0.0.1:8000 (mic access is blocked on some plain-HTTP origins) and microphone permission allowed. |
| No email ever arrives with a code | Expected in Demo mode. Nothing is emailed; use 123456. Outside Demo mode, check TERMII_API_KEY, TERMII_EMAIL_CONFIG_ID, and TERMII_SEND_IN_DEBUG=True for local delivery. |
| Payment link opens a Locktrans.AI page instead of PayPal | That's the local-dev simulated checkout (DEMO_SIMULATE_PAYMENTS=True). Click Confirm simulated payment. Judging and hosted demos always use real PayPal sandbox checkout instead. |
| Seller payout email looks masked | Expected for the buyer view. The seller sees the full PayPal email. |
| The other person's chat does not update | Keep the tab open and visible for about 10 seconds; webchat polls for updates. A full refresh restarts the chat by design: resume with "continue LKTR..." plus 123456. |
| WhatsApp bot does not reply locally | WhatsApp needs a public HTTPS webhook. Run a tunnel such as cloudflared tunnel --url http://127.0.0.1:8000, set the callback to https://<tunnel-host>/webhooks/whatsapp/, and fill in all WHATSAPP_* values. Not needed for the web demo. |
Address already in use on port 8000 |
Stop the old server (Ctrl+C in its terminal) or run python manage.py runserver 8001 and open that port instead. |
| Page loads but buttons or mic do nothing | Hard refresh (Ctrl+Shift+R). After pulling new code, also re-run pip install -r requirements.txt and python manage.py migrate. |
Copy .env.example → .env. Never commit .env.
| Var | Required | Default | Notes |
|---|---|---|---|
DJANGO_SECRET_KEY |
prod only | dev fallback | Must be set when DJANGO_DEBUG=False |
DJANGO_DEBUG |
, | False |
Set True locally. SQLite is used when True |
DJANGO_ALLOWED_HOSTS |
prod only | 127.0.0.1,localhost |
Comma-separated |
DATABASE_URL |
prod only | , | Postgres connection string (ssl_require=True). Required: without it the app has no production database configured |
DEMO_MODE |
judges | False |
True stubs Termii OTP delivery and PayPal payments. AI and escrow logic stay real |
DEMO_OTP_CODE |
judges | 123456 |
Universal verification code accepted only while DEMO_MODE=True |
DEMO_ALLOW_PROD |
— | False |
Explicit opt-in allowing Demo mode with DJANGO_DEBUG=False (isolated demo deployments only) |
WHATSAPP_MEDIA_MAX_BYTES |
— | 8388608 |
Cap on downloaded WhatsApp voice notes, separate from the transcription cap |
PAYPAL_CLIENT_ID |
yes | PayPal app client ID (sandbox for testing, live for prod) | |
PAYPAL_CLIENT_SECRET |
yes | PayPal app secret | |
PAYPAL_MODE |
— | sandbox |
sandbox or live |
PAYPAL_WEBHOOK_ID |
for webhooks | PayPal webhook ID for signature verification | |
TERMII_API_KEY |
yes | dummy_key |
Termii API key for email OTP |
TERMII_EMAIL_CONFIG_ID |
yes | default_config |
Termii email config/channel ID |
TERMII_SEND_IN_DEBUG |
, | False |
Set True for live local OTP delivery (costs credit) |
INFERENCE_API_KEY / INFERENCE_BASE_URL / INFERENCE_MODEL |
for AI chat | , | Any OpenAI-compatible chat endpoint |
AGENT_MAX_ITERATIONS |
, | 8 |
Tool-call cap per chat turn. Keep Procfile web timeout above the worst case (AGENT_REQUEST_TIMEOUT + transcribe + PayPal) |
AGENT_REQUEST_TIMEOUT |
, | 60 |
Seconds per inference call |
CACHE_BACKEND / CACHE_LOCATION |
, | locmem | Swap for Redis etc. in multi-worker deploys; sessions stay database-backed |
SESSION_ENGINE |
, | db sessions | Override only if you know sessions will follow it |
MODEL_API_KEY |
for voice | , | Meta Model API key (Muse transcribe; ~$0.18/hr audio) |
ASR_BASE_URL |
, | https://api.meta.ai |
Transcription endpoint |
ASR_MODEL |
, | muse-voice-transcribe-1.0 |
STT model |
VOICE_MAX_BYTES |
, | 8388608 |
Upload cap per voice note |
VOICE_TIMEOUT |
, | 60 |
Transcription request timeout |
WHATSAPP_ACCESS_TOKEN |
for WhatsApp | , | Cloud API token |
WHATSAPP_PHONE_NUMBER_ID |
for WhatsApp | , | Sending number ID |
WHATSAPP_BUSINESS_ACCOUNT_ID |
, | , | Meta business account |
WHATSAPP_WEBHOOK_VERIFY_TOKEN |
for WhatsApp | , | Must match Meta dashboard |
WHATSAPP_APP_SECRET |
prod | , | Enforces X-Hub-Signature-256 validation |
WHATSAPP_API_VERSION |
, | v21.0 |
Graph API version |
EMAIL_HOST / EMAIL_PORT / EMAIL_HOST_USER / EMAIL_HOST_PASSWORD / EMAIL_USE_TLS |
prod | console backend in DEBUG | SMTP for invitation mail |
DEFAULT_FROM_EMAIL |
, | Locktrans.AI <no-reply@…> |
Invitation sender |
GATEWAY_HTTP_TIMEOUT |
, | 15 |
Seconds before PayPal/Termii/WhatsApp calls abort |
OTP_ISSUE_COOLDOWN_SECONDS |
, | 60 |
Min gap between OTPs to same address/purpose |
LOG_OTP_TO_CONSOLE |
, | False |
Set True locally to print codes to logs |
LOG_LEVEL |
, | INFO |
Root + escrow logger level |
CSRF_TRUSTED_ORIGINS |
prod only | , | e.g. https://escrow.example.com |
SECURE_SSL_REDIRECT |
, | True (prod) |
Set False only behind a TLS-terminating proxy that needs it |
| Path | Name | Purpose |
|---|---|---|
/ |
home |
Landing + embedded AI chat |
/create/ |
create_contract |
New escrow |
/join/ |
join_escrow_page |
Join via code (?code= prefills) |
/verify/<code>/ |
verify_otp |
Creator OTP → invites counterparty |
/escrow/<code>/ |
contract_detail |
Detail + actions (HTMX panel) |
/escrow/<code>/verify/ |
counterparty_verify_otp |
Counterparty OTP → opens funding |
/escrow/<code>/pay/ |
initiate_payment |
Start PayPal checkout (creates Order, returns approve link) |
/escrow/<code>/callback/ |
payment_callback |
PayPal return (captures Order, verification fallback) |
/webhooks/paypal/ |
paypal_webhook |
Payment/payout confirmation (signature-checked, deduped) |
/webhooks/whatsapp/ |
whatsapp:webhook |
WhatsApp verify + inbound + statuses |
/assistant/ |
agent:chat |
Website AI assistant |
/assistant/send/ |
agent:chat_send |
Chat turn |
/assistant/voice/ |
agent:chat_voice |
Voice note → transcript → turn |
/assistant/transcribe/ |
agent:transcribe_field |
Field-level transcription (JSON) |
/assistant/new/ |
agent:chat_new |
Fresh thread (full page loads always restart) |
/assistant/verify/ |
agent:chat_verify |
Email-code verification form |
/assistant/dismiss/ |
agent:chat_dismiss |
Discard a pending proposal |
/assistant/poll/ |
agent:chat_poll |
Live chat updates for open pages (204 when nothing new). Polls every ~10s while the tab is visible; safe during recording, typing, or an open proposal — it only returns rendered thread state |
/demo/pay/<code>/ |
demo_pay |
Simulated checkout, Demo mode only (404 when off) |
/escrow/<code>/dispatch/ /receipt/ /release/ /dispute/ /seller-dispute/ /cancel/ /vault/ |
, | Lifecycle actions |
/my-escrow/ /my-escrow/verify/ /my-escrow/list/ |
my_escrow* |
Email+OTP deal lookup |
Admin: /admin/ (escrow ops, OTPs, vaults, payments, payouts, refunds, webhooks, audit trail)
config/ # settings, urls, wsgi/asgi
escrow/ # models, views, forms, services, lifecycle.py, invitations.py,
# gateways/, notifications.py, bank_verification.py, tests
agent/ # chat loop, inference client, tool registry, views
whatsapp/ # Cloud API adapter, webhook, conversation flow
voice/ # Muse transcription (ffmpeg convert + API client)
templates/ # base.html (design system), home.html, agent/, escrow/
static/js/ # voice.js (hold-to-record mic + typing indicator + chat poll)
manage.py
requirements.txt
Procfile # web: gunicorn / worker: auto_release_escrow
runtime.txt
Design tokens, components, and responsive rules live in templates/base.html (no separate frontend build; voice.js is the only first-party script). Run python manage.py test before pushing UI changes: escrow/tests.py::SmokeTest renders every page and checks URL reversal, and the suite covers the agent, WhatsApp, voice, and money-movement paths.
Bounded tool-using loop (agent/loop.py): user message → model → approved tool call → backend result → reply. A fixed registry of tools (agent/registry.py), all authenticated against the session-verified email and the escrow state machine, model arguments are untrusted input.
- Consequential tools (create, invite, join, pay, dispatch/receipt, payout email, release, dispute) need exact fresh confirmation. A clear "yes" executes the backend-stored proposal directly, so users are never asked to confirm twice.
- OTPs are consumed by the backend, never the model; codes are redacted from model context.
- Model outages degrade to the manual forms; nothing is ever claimed from conversation alone.
The agent talks to any OpenAI-compatible /v1 endpoint (agent/client.py), so switching providers is a config change, not a code change. Two ways to run Muse Spark Open on Modal:
A. Shared endpoint (recommended). Modal already hosts it on a managed, per-token pool — no GPUs to provision:
- Create it:
modal endpoint create --shared --model meta-models/Muse-Spark-Open(or the Endpoints tab in the dashboard; copy the URL and model name from its request examples). - Mint a proxy token:
modal workspace proxy-tokens create, then join aswk-<id>.ws-<secret>. - Wire Django (
.envlocally, Render dashboard in prod):INFERENCE_BASE_URL=https://inference.us-west.modal.direct/v1,INFERENCE_API_KEY=<joined proxy token>,INFERENCE_MODEL=<endpoint hostname from the dashboard>. - The loop sends
Modal-Routing-Affinity-Keyper conversation automatically, keeping each agent run on one warm container; reasoning output needs the generousINFERENCE_MAX_TOKENSbudget (default 16384) so answers aren't cut off withfinish_reason == 'length'.
Note: shared-endpoint tokens bill from the first call (outside the free compute credits) — fine for a demo, watch it in production.
B. Self-host with vLLM. modal_app.py in this repo runs the open weights behind the same OpenAI shape with Bearer-token auth and scale-to-zero; see its header for the exact modal secret create / modal deploy steps. Useful if you need a private pool or a different checkpoint; heavier and slower to cold-start than A.
Any OpenAI-compatible server works here — a Modal shared endpoint or your own deployment — with no code changes.
Hold the chat mic (web) or send a WhatsApp voice note → voice/transcriber.py: ffmpeg (pip-bundled binary, no apt) converts to 16-bit mono WAV → Muse Voice Transcribe (PUSH_TO_TALK, English bias, escrow vocabulary). The transcript feeds the normal agent turn, including bare 6-digit codes; cancelled or sub-400ms holds are discarded and never transcribed. Failures degrade to "type instead"; throttled (20/hr per session) and size-capped since transcription is metered.
- Set
DJANGO_DEBUG=False,DJANGO_SECRET_KEY,DJANGO_ALLOWED_HOSTS,DATABASE_URL,CSRF_TRUSTED_ORIGINS, PayPal/Termii/Model/WhatsApp keys, SMTP. The app refuses to boot withoutPAYPAL_CLIENT_ID, with default hosts, or withDEMO_MODEon.EMAIL_HOSTis optional: without SMTP, invitation links print to the server log instead of emailing. - Build:
pip install -r requirements.txt && python manage.py collectstatic --noinput && python manage.py migrate - Start:
gunicorn config.wsgi:application --bind 0.0.0.0:$PORT --workers 3 --timeout 90(timeout must cover the slowest chat turn plus voice transcription) - Scheduler, not a persistent worker: run
python manage.py auto_release_escrowfrom cron/beat on a schedule (theProcfileworker entry documents the one-shot command; a long-lived dyno running it would just exit) - Register webhooks: PayPal developer dashboard →
/webhooks/paypal/(setPAYPAL_WEBHOOK_ID); Meta dashboard →/webhooks/whatsapp/(+ verify token). - Run the test-mode end-to-end (create → join → test card → dispatch → receipt → release) before going live.
- Prod enforces
Securecookies, HSTS (1yr),SECURE_PROXY_SSL_HEADER,X-Frame-Options: DENY.
- No passwords, OTP-gated sessions expire after
SESSION_COOKIE_AGE(default 24h); OTPs hashed, short-lived, attempt-limited, cooldown-guarded, single-use. - WhatsApp numbers are endpoints, not identity; verified email is the actor everywhere.
- Security headers ship by default:
X-Frame-Options: DENY, nosniff, same-origin referrer, microphone-only permissions policy, and a Content-Security-Policy covering self, jsDelivr, and Google Fonts. - Webhook signatures validated (PayPal + WhatsApp); duplicate events ignored via unique constraints.
- Amount + currency verified on every funding confirmation; payouts are claimed once, parked
uncertainon timeouts (never blind-retried), and only atransfer.successwebhook completes an escrow — failed or reversed transfers stay inpending_payoutfor reconciliation with both parties notified. - Post-funding cancellation initiates an explicit provider refund (
initiate_refund) tracked toinitiatedorfailed; a cancelled escrow counts as refunded only after the provider confirms. - Agent cannot resolve disputes or bypass auth; payout release needs buyer confirmation plus a verified seller PayPal email, and every consequential call is confirmation-gated, with prompt-injection and tool-spoofing covered by tests.
- Keep
LOG_OTP_TO_CONSOLE=Falseoutside local dev.