AgentRegisterResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/depixapp-com/json-schema/depixapp-com-agent-register-response-schema.json",
  "title": "AgentRegisterResponse",
  "description": "Agent onboarding result — the ONLY response that ever carries key plaintexts and the webhook secret.",
  "x-generated": "2026-11-05",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/depixapp-com-openapi.yml#/components/schemas/AgentRegisterResponse",
  "type": "object",
  "required": [
    "response"
  ],
  "additionalProperties": false,
  "properties": {
    "response": {
      "type": "object",
      "description": "Envelope (legacy contract shape).",
      "required": [
        "agent",
        "merchant",
        "keys",
        "graduation",
        "pacing"
      ],
      "additionalProperties": false,
      "properties": {
        "agent": {
          "type": "object",
          "description": "The created agent account.",
          "required": [
            "username",
            "public_key",
            "account_type"
          ],
          "additionalProperties": false,
          "properties": {
            "username": {
              "type": "string",
              "description": "Account handle (also the merchant slug until graduation)."
            },
            "public_key": {
              "type": "string",
              "description": "The Ed25519 public key registered as the account identity (64 hex)."
            },
            "account_type": {
              "type": "string",
              "enum": [
                "agent"
              ],
              "description": "Always \"agent\" — server-set and immutable."
            }
          }
        },
        "merchant": {
          "type": "object",
          "description": "The auto-created merchant profile.",
          "required": [
            "id",
            "merchant_slug",
            "liquid_address",
            "webhook_secret"
          ],
          "additionalProperties": false,
          "properties": {
            "id": {
              "type": "string",
              "description": "Merchant id (mrc_…)."
            },
            "merchant_slug": {
              "type": "string",
              "description": "Public page slug — equals the username until graduation (anti-squat)."
            },
            "liquid_address": {
              "type": "string",
              "description": "The static receiving address from the request."
            },
            "webhook_secret": {
              "type": "string",
              "description": "ONE-TIME plaintext webhook signing secret (whsec_…). Rotatable later; never shown again."
            }
          }
        },
        "keys": {
          "type": "object",
          "description": "Auto-issued API keys — plaintexts shown ONLY here.",
          "required": [
            "test",
            "live_starter"
          ],
          "additionalProperties": false,
          "properties": {
            "test": {
              "type": "object",
              "description": "Sandbox key with the full default scopes.",
              "required": [
                "id",
                "key",
                "scopes"
              ],
              "additionalProperties": false,
              "properties": {
                "id": {
                  "type": "string",
                  "description": "Key id."
                },
                "key": {
                  "type": "string",
                  "description": "sk_test_… plaintext (one-time)."
                },
                "scopes": {
                  "type": "string",
                  "description": "Space-separated scopes granted to the sandbox key."
                }
              }
            },
            "live_starter": {
              "type": "object",
              "description": "Pre-graduation production key: wallet-only scopes with mandatory low limits.",
              "required": [
                "id",
                "key",
                "scopes",
                "per_tx_limit_cents",
                "daily_limit_cents",
                "starter"
              ],
              "additionalProperties": false,
              "properties": {
                "id": {
                  "type": "string",
                  "description": "Key id."
                },
                "key": {
                  "type": "string",
                  "description": "sk_live_… plaintext (one-time)."
                },
                "scopes": {
                  "type": "string",
                  "description": "Exactly \"wallet_read wallet_write\" — merchant scopes require graduation + a verified domain."
                },
                "per_tx_limit_cents": {
                  "type": "integer",
                  "description": "Mandatory per-transaction cap on this key."
                },
                "daily_limit_cents": {
                  "type": "integer",
                  "description": "Mandatory rolling daily cap on this key."
                },
                "starter": {
                  "type": "boolean",
                  "description": "Always true — marks the auto-issued starter key."
                }
              }
            }
          }
        },
        "graduation": {
          "type": "object",
          "description": "What unlocks full production capability, and where to do it. Graduation is downstream of verification, and an AGENT account verifies by proving control of a registrable domain over DNS — never by settling a number of deposits. Deposits buy nothing here; the two calls below are the whole path.",
          "required": [
            "requires",
            "verify_domain_endpoint",
            "allowed_tlds_endpoint"
          ],
          "additionalProperties": false,
          "properties": {
            "requires": {
              "type": "string",
              "enum": [
                "domain_proof"
              ],
              "description": "The gate, as a machine-readable token — the same one GET /api/verification reports in `missing[]`/`steps[]` and GET /api/agents/status reports in `graduation.blocked_on`."
            },
            "verify_domain_endpoint": {
              "type": "string",
              "description": "Method + path of the call that performs the proof, in two phases: `{domain}` returns the TXT record to publish, `{domain, confirm: true}` resolves it. A successful proof verifies the account, and graduation follows on its own (watch `graduation.blocked_on` on GET /api/agents/status, or the `agent.graduated` webhook)."
            },
            "allowed_tlds_endpoint": {
              "type": "string",
              "description": "Method + path of the public TLD allowlist. Call it before picking a domain — it is what verify-domain will accept, and it avoids a trial-and-error 422."
            }
          }
        },
        "pacing": {
          "type": "object",
          "description": "Read-only account limits so the agent can pace itself without trial-and-error 4xx.",
          "required": [
            "first_deposit_max_cents",
            "unverified_per_tx_max_cents",
            "inter_deposit_delay_hours",
            "payer_velocity",
            "verified_per_tx_deposit_max_cents",
            "verified_per_tx_withdraw_send_max_cents",
            "verified_per_tx_withdraw_receive_max_cents"
          ],
          "additionalProperties": false,
          "properties": {
            "first_deposit_max_cents": {
              "type": "integer",
              "description": "Cap on the account's first deposit."
            },
            "unverified_per_tx_max_cents": {
              "type": "integer",
              "description": "Per-deposit cap before verification."
            },
            "inter_deposit_delay_hours": {
              "type": "integer",
              "description": "MINIMUM settlement delay applied to deposits 2–5 of ANY account — verified or not, personal deposit or Pix checkout, since the account has one deposit ledger. The DePix payout of each of those deposits is held AT LEAST this many hours (deposit status `delayed`). It is a floor, not the whole answer: the rules that hold a deposit compose by taking the LONGEST, so a deposit 2–5 too large to count as pacing, or one under risk review, is held for the account's trust-level window instead — which is longer. Read `vault_window_hours` on GET /api/vault/status and pace against the greater of the two before promising anyone a release time. Deposit 1 settles immediately and deposit 6 onward is governed by the receive cap and the instant lane. It does NOT block CREATING the next deposit — you never have to wait between creates because of this field."
            },
            "payer_velocity": {
              "type": "object",
              "description": "Per-payer deposit velocity gate.",
              "required": [
                "max_per_window",
                "window_minutes"
              ],
              "additionalProperties": false,
              "properties": {
                "max_per_window": {
                  "type": "integer",
                  "description": "Deposits allowed per payer per window."
                },
                "window_minutes": {
                  "type": "integer",
                  "description": "Window length in minutes."
                }
              }
            },
            "verified_per_tx_deposit_max_cents": {
              "type": "integer",
              "description": "Per-deposit cap after verification, on `amountInCents` — what the payer sends on POST /api/deposit."
            },
            "verified_per_tx_withdraw_send_max_cents": {
              "type": "integer",
              "description": "Per-withdrawal cap after verification, on `depositAmountInCents` — the DePix the wallet sends. Mirrors the request schema maximum."
            },
            "verified_per_tx_withdraw_receive_max_cents": {
              "type": "integer",
              "description": "Per-withdrawal cap after verification, on `payoutAmountInCents` — the BRL the destination key receives. Mirrors the request schema maximum; the provider bounds each request field at the same figure, so this equals the send cap."
            }
          }
        }
      }
    }
  }
}