---
title: "Turn the DePix direct rail on or off"
method: POST
path: "/api/agents/depix-pay"
tags: ["agents"]
---

# Turn the DePix direct rail on or off

`POST /api/agents/depix-pay`

## Request

- Base URL: `https://api.depixapp.com`
- URL: `https://api.depixapp.com/api/agents/depix-pay`
- Auth: none required

Registers (or removes) the dedicated confidential Liquid address the agent's merchant is paid at on the DePix rail, so its checkouts can be paid in DePix on-chain instead of only by Pix. Auth is the agent keypair signature — the human twin of this endpoint is password-gated dashboard surface, which an agent account can never satisfy. Enabling requires the address AND its blinding private key: the key is proof of possession (the address is rebuilt from it and must match) and it is the ONLY thing that lets us read the amounts arriving there. It is sealed at rest and never returned. The address must be confidential (lq1…) and exclusive — the payout and split addresses are refused. Disabling takes no key and deletes the grant; an address with a DePix payment still in flight keeps its key until that checkout is terminal. Requires a verified account (for an agent, that is the domain proof) and rejects a suspended merchant.

## Request body

- AgentDepixPayRequest: Turn the DePix direct rail on or off for the agent's own merchant. Authenticated by the agent keypair signature — the per-request proof-of-possession IS the step-up the human door gets from a password. Enabling ALWAYS needs a fresh (address, blinding_key) pair: there is no re-activation without one, because re-activating means a brand new dedicated address.
  - `enabled` boolean, required: true → register the dedicated address and start watching it. false → turn the rail off and delete the view key (no other field is read, and none is required).
  - `address` string: The dedicated CONFIDENTIAL Liquid address (lq1…) this merchant will be paid at. Required when enabled is true. An unconfidential ex1/base58 address is refused: it would publish every amount received to the whole world. It must also be exclusive — never the merchant's payout or split address.
  - `blinding_key` string: The 32-byte blinding PRIVATE key of that address, hex. It grants visibility of the amounts arriving at that ONE script and nothing else: no spending power, no other address, no descriptor. Sent once, stored sealed, and deleted when the rail is turned off.
  - `derivation_index` integer, nullable: Optional wallet derivation index of the address, echoed back so the wallet can keep the index reserved across a restore. Non-negative integer.

## Response `200`

The rail's new state.

- AgentDepixPayResponse: The rail's new state.
  - `response` union, required: Enabled and disabled answer different questions, so they carry different fields.
    - object: The rail is on and this address is being watched.
      - `depix_pay_enabled` true, required: Always true here.
      - `depix_pay_address` string, required: The registered dedicated address (lower-cased).
      - `depix_derivation_index` integer, nullable, required: The index sent in, echoed back; null when none was sent.
      - `depix_discount_pct` integer, required: The discount currently granted on this rail, in percent. Unchanged by this call.
    - object: The rail is off. `view_key_deleted` says whether any viewing grant was actually destroyed; an address with a DePix payment still in flight keeps its key until that checkout is terminal, otherwise the payer's money would land on a script nobody watches.
      - `depix_pay_enabled` false, required: Always false here.
      - `view_key_deleted` boolean, required: Whether at least one view key was deleted.
      - `pending_addresses` integer, required: How many addresses kept their key because a DePix checkout there is still open.

## Other responses

- `400`: Malformed body (validation_error with details.field), a non-confidential or undecodable address (depix_address_unsupported), an address that is not exclusive or is already registered (depix_address_conflict), or a blinding key that does not belong to the address (invalid_blinding_key).
- `401`: Signature chain failed or unknown agent key.
- `403`: Blocked (account_blocked), suspended (account_suspended), or the account is not verified yet (verification_required — for an agent, prove a domain).
- `429`: Rate limited (per-IP, per-key or per-merchant window). Retry after `retry_after` seconds (also in the Retry-After header).
- `503`: The rail's key-encryption key is not configured, so no view key could be stored and read back; the nonce anti-replay store is unavailable (fail-CLOSED); or the agent program is globally disabled (agents_disabled).

---

[API](https://skmtc.dev/depixapp/apis/depix-api.md) · [All operations](https://skmtc.dev/depixapp/apis/depix-api/llms.txt) · [OpenAPI document](https://skmtc.dev/depixapp/apis/depix-api/revisions/04094536dd0f?raw)