DePix App Gateway

initis a human ceremony at a terminal, never an MCP tool.It prints your 12-word seed backup, so it refuses to run when stdin/stdout are not a real TTY, and no agent can invoke it:

npx -y @depixapp/mcp init # create a new wallet npx -y @depixapp/mcp init --restore # import an existing 12-word mnemonic

It asks for (or generates) a passphrase — never echoed — walks you through the backup ritual, and finishes by printing the exactmcpServersblock to paste, with the passphrase left as a placeholder for you to fill in:

{ "mcpServers": { "depix": { "command": "npx", "args": ["-y", "@depixapp/mcp"], "env": { "DEPIX_API_KEY": "sk_test_YOUR_KEY", "DEPIX_WALLET_PASSPHRASE": "<the passphrase you typed>", "DEPIX_WALLET_DIR": "/Users/you/.depix-wallet" } } } }

Clear your terminal scrollback afterwards. Restart your MCP client and ask it to runwallet_status.

Run the server directly to sanity-check:

DEPIX_API_KEY=sk_test_YOUR_KEY npx -y @depixapp/mcp

Self-hosting over HTTP is NOT trivially safe.The wallet tools have no auth of their own and the seed is loaded process-wide. Over localstdiothat is fine. Exposed over HTTP, anyone who reaches the port can drain the wallet — bind to localhost and add your own bearer/mTLS + network isolation, or don't.

Quickstart 3 — Sandbox testing (the full loop)

Always test with ansk_test_key beforesk_live_. Sandbox QRs are non-payable placeholders (SANDBOX-…-DO-NOT-PAY).
-

create_checkout—amountis always required; on the defaultPixrailpayer_tax_numberis too (the CPF/CNPJ is required even in sandbox). Use a test CPF like52998224725:

{ "amount": 1500, "payer_tax_number": "52998224725" }

Returns achk_…id, apayment_url, a sandboxpix.qr_code, andis_live: false.

simulate_checkout_payment—{ "checkout_id": "chk_…" }marks the sandbox checkout paid (sandbox-only; live checkouts returnsandbox_only).

wait_for_checkout—{ "checkout_id": "chk_…" }. The server polls internally and streams progress; you makeonecall and it returns{ "status": "completed", "terminal": true }— no client-side polling loop.

You can also read a synthetic deposit:get_deposit_statuswith asandbox_…id returnsdepix_sent.

Charging on the DePix rail instead of Pix

create_checkouttakespayment_method. The default"pix"is the flow above. With"depix"the payer sends DePixwallet-to-wallet on Liquidto the merchant's dedicated address — there is no Pix QR and no payer document:

{ "amount": 9990, "payment_method": "depix", "expected_discount_pct": 10 }

The response carriesdepixinstead ofpix:address, theexactamount_centsto send (face amount minus the merchant's discount, minus a sub-cent-window adjustment that makes the value unique — that uniqueness is how the payment is matched), the decimalamounta wallet signs,asset_idand a ready-to-scanuri. Send any other amount or any other asset and the payment cannot be credited automatically, and an on-chain payment is irreversible.

Settlement is observed on-chain:approvedat the first confirmation (~1 min),completedat the second.expires_inaccepts 300–3600 s here (default 1800) instead of the Pix rail's 300–1200. The rail must be enabled by the merchant — otherwise the API answersdepix_not_enabled. Sandbox DePix checkouts are deliberately unpayable (placeholder address,uri: null); drive them withsimulate_checkout_payment.

22 gateway tools— available at both levels. Amounts are BRL cents.

Charges (cobranças).create_productwithkind: "charge"creates a payment link with adue dateand optional late fine/interest — rent, tuition, an instalment. It is served atpay.depixapp.com/c/{id}, never appears on the merchant's public store, and the amount is recomputed on each visit (base + fine + pro-rata interest for the current cycle). Withrecurrencethe same link keeps working month after month, settling the oldest unpaid cycle first.list_productsdoesnotreturn charges unless you passkind: "charge"(or"all"); charge rows then carrycharge_state— current cycle, days late, today's total.

Do not confuse it withcreate_checkout, which mints aone-offpayment that is paid once and is short-lived. A charge is the standing one.

The last six are the support channel: open a ticket, poll for the human reply, reply back, attach a screenshot or diagnostic/log file (base64, ~3 MB), or close it (up to 5 open per account). Replies are not pushed — pollget_support_ticket. Amounts are BRL cents. A tool call whose key lacks the required scope returns aninsufficient_scopetool error naming the missing scope — that is the only way to discover a missing scope (the API never lists a key's scopes).

wallet_convertis the primary conversion surface (wallet_quoteenumerates the routes); the provider-level tools are the escape hatch.wallet_shift_usdtis the onecustodialroute (SideShift) and says so. Amounts carry their unit in the field name:amount_centsis BRL cents,amount_satsis the asset's base units.

There is deliberatelynotool to export the seed, change guardrails, edit the payout addresses, or pay a merchant checkout QR — not even from a fully injected model.

Local (npx) level only — the wallet half:

There is deliberatelynoenv for an API key, Eulen token, HMAC or DB credential in the remote server. In HTTP mode the key arrives per-request in theAuthorizationheader. The wallet passphrase and seed existonlyon the operator's machine — the hosted deployment reads neither and has no code that could.

- POST /mcp— the MCP Streamable HTTP endpoint (DELETEends a session;GETreturns 405 — this stateless server offers no standalone SSE stream).
- GET /.well-known/mcp.json— minimal discovery document.
- GET /api/health(also/) — service status.

npm install npm test # vitest npm run typecheck # tsc --noEmit npm run lint # eslint npm run build # compile src (incl. the vendored engine) → dist npm run guard:hosted # the hosted deployment has no path to the wallet engine npm run licenses:check # THIRD_PARTY_LICENSES matches the prod dep tree npm run vendor:check # src/vendor matches the pinned engine commit

SetDEPIX_TEST_KEY=sk_test_…to run the real-sandbox e2e test (test/e2e/sandbox.test.ts), otherwise it is skipped.

The 27 wallet tools come from the DePix App wallet engine, whose source isvendoredhere from a pinned commit rather than taken as an npm dependency.

- vendor/engine.pin.jsonis the single source of truth (repo + full 40-char SHA).
- npm run vendor:engineregeneratessrc/vendor/from that commit, stamping each file with the Apache-2.0 header and its provenance.Never hand-edit anything undersrc/vendor/— change it upstream and bump the pin.
- The tree iscommittedbecausenpm cirunsprepare→build: the sources must exist before any install step could fetch them. Reproducibility comes fromnpm run vendor:check, which CI runs against a fresh checkout of the pinned commit and fails on a single byte of drift.

api/mcp.ts→src/http.ts→src/server.tshaszeroimport path tosrc/vendor/. Neither repo runs a tree-shaking bundler, so that import graph is the whole guarantee.scripts/check-hosted-isolation.mjsenforces it twice — a static walk of the TypeScript sources and a@vercel/nfttrace of the compiled entries — and its--self-testproves both checks reject a poisoned entry. Onlysrc/stdio.ts→src/unified.tsmay reach the engine.

CI(.github/workflows/ci.yml) runs typecheck + lint + test + build + all three guards on every push tomainand every PR, on Node 22 and 24 — that is the correctness gate.