DePix App agent-spec

The normative signing spec, test vectors, runnable examples, and generated collections for building agents on the DePix App API — the non-custodial Pix↔DePix payment gateway on the Liquid Network.

This repo is deliberately thin. The canonical, living sources of truth live at depixapp.com and in the SDK/MCP repos. This repo holds only what does not live anywhere else: the precise request-signing spec, cryptographic test vectors, runnable verifiers, and collections generated from the live OpenAPI. Everything here is guarded against drift in CI.

Where the canonical sources live

You want…	Go to
Machine-readable API schema	https://api.depixapp.com/openapi.json (OpenAPI 3.1)
Agent quickstart / discovery	https://depixapp.com/llms.txt · https://depixapp.com/.well-known/agent.json
Human API reference	https://depixapp.com/docs/en/
MCP server (merchant/gateway)	https://github.com/depixapp/depix-mcp
Wallet SDK (holds funds, signs)	https://github.com/depixapp/depix-sdk

What lives here (and nowhere else)

signing/
  agent-auth.md            Normative Ed25519 request-signing spec (the canonical string)
  webhook-signature.md     Outbound webhook signature (X-DePix-Signature) + retry policy
  limits.md                SDK client-side guardrails vs server-side agent pacing
  vectors/
    agent-auth.json        TEST-ONLY key -> signed requests (GET, POST, empty-body edge case)
    webhook.json           TEST-ONLY secret + payload -> expected HMAC
examples/
  verify-webhook/{node,python,go}   Verify webhook.json (run in CI)
  sign-request/{node,python}        Reproduce agent-auth.json signatures (run in CI)
collections/
  gen-collections.mjs      Generates Postman + Bruno collections from the live OpenAPI
  postman/ , bruno/        The generated collections (committed)
discovery/
  agent.json, llms.txt     Versioned snapshot of the live discovery surface
  canonical.json           Pinned values the drift guard checks against live
mcp/README.md              Pointer to depix-mcp + the two (non-interchangeable) MCP servers
scripts/
  gen-vectors.mjs          Regenerate + self-verify the test vectors
  verify-vectors.mjs       Re-verify the committed vectors (CI guard against rot)
  pull-canonical.mjs       Fail CI if the live sources drift from the pins

Quickstart — discovery → sandbox → prod

An agent moves through three stages; this repo supports each.

1. Discover. Read the machine-first surface — GET /llms.txt, GET /openapi.json, GET /.well-known/agent.json — to learn endpoints, auth, scopes and fees. Import a ready-made collection into Postman or Bruno to click through the core flow.
2. Sandbox. Self-onboard with an Ed25519 keypair (POST /api/agents/register, signed per signing/agent-auth.md), receive an sk_test_ key, create a checkout and complete it with simulate-payment — no real money, no Brazil, no card. Validate your signing implementation against signing/vectors/ before you ever hit the network.
3. Production. Use your sk_live_ key. Verify inbound webhooks per signing/webhook-signature.md (copy an example), and pace against your account's live limits (signing/limits.md). DePix is non-custodial end to end: the API never holds funds or keys, and the companion @depixapp/sdk wallet signs transactions with a seed the agent controls.

Run it locally

npm test          # re-verify vectors + run the Node verify/sign examples
node scripts/verify-vectors.mjs            # re-verify all committed vectors
node examples/verify-webhook/node/verify.mjs
node examples/sign-request/node/sign.mjs
python3 examples/verify-webhook/python/verify.py
( cd examples/verify-webhook/go && go run . )
node collections/gen-collections.mjs       # regenerate collections from live OpenAPI
node scripts/pull-canonical.mjs            # check for drift against the live sources

The test vectors are the highest-value content here: every one is generated by actually running the signing algorithm and is re-verified in CI, so a wrong vector can never ship. They let an integrator in any language confirm their implementation before touching the network.

How drift is prevented

Because the living sources evolve, three CI guards keep this repo honest:

• scripts/verify-vectors.mjs re-verifies every signing vector (they can't rot).
• scripts/gen-vectors.mjs --check proves the committed vectors reproduce exactly.
• scripts/pull-canonical.mjs fails if the live OpenAPI/agent.json move ahead of the pinned values in discovery/canonical.json (skips gracefully on a network hiccup — it only fails on real drift).

License

Apache-2.0 — this is interoperability material meant to be copied into your own integrations.