{
  "openapi": "3.1.0",
  "info": {
    "title": "Hodle API",
    "version": "1.0.0",
    "description": "Lightning + PIX in one API. Issue Lightning invoices, run PIX on-ramps and off-ramps, transfer stablecoins, and ship KYC."
  },
  "servers": [
    {
      "url": "https://api.hodle.com.br",
      "description": "Production"
    }
  ],
  "security": [{ "bearerAuth": [] }],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Authenticate every request with `Authorization: Bearer YOUR_API_KEY`."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": false },
          "error": { "type": "string", "example": "Validation failed" },
          "errorCode": { "type": "string", "nullable": true, "example": "KYC_REQUIRED" },
          "details": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "field": { "type": "string" },
                "message": { "type": "string" }
              }
            }
          }
        }
      },
      "PixKeyType": {
        "type": "string",
        "enum": ["PHONE", "CPF", "EMAIL", "RANDOM", "CNPJ"]
      },
      "Network": {
        "type": "string",
        "enum": ["polygon", "base", "tron", "solana", "lightning"]
      },
      "DepositAssetRequest": {
        "type": "object",
        "required": ["value", "asset"],
        "properties": {
          "value": { "type": "integer", "minimum": 100, "example": 5000, "description": "Amount in BRL cents. Minimum 100 (R$1.00)." },
          "address": { "type": "string", "example": "lnbc500u1pj...", "description": "Destination address. BOLT11 invoice or LNURL email for LIGHTNING; EVM address for USDT, USDC, USDCE, and BRLA on EVM networks; base58 Solana address for USDT and USDC on solana; spark1... address for BTC and DEPIX on spark, or a Liquid address for DEPIX on liquid. Omit for BRS (or send one of the account's own wallets on that network)." },
          "asset": { "type": "string", "enum": ["LIGHTNING", "USDT", "USDC", "USDCE", "BRLA", "BRS", "DEPIX", "BTC"], "example": "LIGHTNING" },
          "network": { "type": "string", "enum": ["polygon", "arbitrum", "base", "gnosis", "tron", "solana", "lightning", "spark", "liquid"], "description": "Network. Required when `asset` is `USDT`, `USDC`, `USDCE`, or `BRLA`; `BRS` supports `solana` (default) and `base` (delivered to the account's own Base wallet); `BTC` uses `spark`; `DEPIX` uses `spark` or `liquid`. Not needed for `LIGHTNING`. USDT and USDC on `solana` deliver to any Solana wallet; Solana delivery must be enabled on your account." },
          "externalId": { "type": "string", "description": "Idempotency key — generated if not provided. Repeating your own externalId returns the original deposit (same walletCharge and qrCode) with 200; an externalId used by a deposit that is not yours answers 409." },
          "taxId": { "type": "string", "description": "Beneficiary CPF, digits only. Omit for the account holder." },
          "subAccountId": { "type": "string", "description": "Create the deposit on behalf of this subaccount. Defaults to the main account." },
          "walletDeclaration": { "$ref": "#/components/schemas/WalletDeclaration" }
        }
      },
      "WalletDeclaration": {
        "type": "object",
        "description": "Holder of the destination wallet, reported to the Central Bank of Brazil (ACAM). Required on the first deposit to an external wallet not yet declared on the account; not needed for the account's Hodle wallets or for a wallet already declared (saved per address and network). Mandatory from November 15, 2026. See /docs/wallet-declaration.",
        "required": ["isSelfCustody", "counterpartyName", "counterpartyCountry", "reason"],
        "properties": {
          "isSelfCustody": { "type": "boolean", "enum": [true], "description": "Must be true: the holder controls the wallet's private keys." },
          "counterpartyName": { "type": "string", "minLength": 1, "maxLength": 100, "example": "Example Holdings LLC", "description": "Full name or legal name of the wallet holder." },
          "counterpartyCountry": { "type": "string", "pattern": "^[A-Z]{2}$", "example": "US", "description": "ISO 3166-1 alpha-2 country of residence (person) or incorporation (company). BR makes the transfer domestic." },
          "reason": { "type": "string", "minLength": 3, "maxLength": 500, "example": "Purchase of virtual assets for the company treasury", "description": "Why the money is sent to this wallet." },
          "purposeCode": { "type": "string", "example": "91992", "description": "Required when counterpartyCountry is not BR. Must be valid for the operation's USD band: 91992 (up to USD 50,000) or 12186 (above) for a purchase of virtual assets." }
        }
      },
      "DepositAssetResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "externalId": { "type": "string" },
          "qrCode": { "type": "string", "nullable": true },
          "fee": { "type": "number" },
          "fxRateAtTx": { "type": "number" },
          "walletCharge": { "type": "string", "nullable": true }
        }
      },
      "LightningInvoiceRequest": {
        "type": "object",
        "required": ["value"],
        "properties": {
          "value": { "type": "integer", "minimum": 10, "maximum": 25000, "example": 1000, "description": "BRL cents. Min R$0.10, max R$250.00." },
          "pixKey": { "type": "string", "example": "user@email.com" },
          "pixKeyType": { "$ref": "#/components/schemas/PixKeyType" },
          "qrCode": { "type": "string", "description": "PIX BR Code copy-paste — mutually exclusive with `pixKey`." },
          "refundAddress": { "type": "string", "description": "Lightning address to refund to on failure." }
        }
      },
      "LightningInvoiceResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "invoice": { "type": "string", "example": "lnbc32310n1p5u2g2qsp5..." },
          "valueInSatoshis": { "type": "integer", "example": 276190 },
          "pixKey": { "type": "string", "nullable": true },
          "qrCode": { "type": "string", "nullable": true },
          "valueInBrl": { "type": "string", "example": "1000.00" },
          "fee": { "type": "string", "example": "170.00" }
        }
      },
      "WalletKeysResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "data": {
            "type": "object",
            "properties": {
              "protectedSymmetricKey": { "type": "string" },
              "email": { "type": "string", "format": "email" }
            }
          }
        }
      },
      "WalletGetResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "type": "object",
            "properties": {
              "userId": {
                "type": "string"
              },
              "subAccountId": {
                "type": "string",
                "nullable": true,
                "description": "Avenia subaccount the wallet belongs to, when there is one."
              },
              "syncedAt": {
                "type": "string",
                "format": "date-time",
                "nullable": true
              },
              "addresses": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                },
                "example": {
                  "polygon": "0x9aB7a1...",
                  "base": "0x9aB7a1...",
                  "tron": "TQn9Y2..."
                }
              },
              "balances": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "asset": {
                      "type": "string"
                    },
                    "network": {
                      "type": "string"
                    },
                    "amount": {
                      "type": "string"
                    }
                  }
                }
              },
              "walletId": {
                "type": "string",
                "description": "Selected wallet ID, returned when walletId was supplied."
              }
            }
          }
        }
      },
      "WalletTransferRequest": {
        "type": "object",
        "required": ["network", "recipientAddress", "amount", "walletPin", "protectedSymmetricKey"],
        "properties": {
          "network": { "type": "string", "enum": ["polygon", "base", "tron"] },
          "recipientAddress": { "type": "string", "example": "0x9aB7a1c2D3e4F5061728394A5B6C7D8E9F0a1B2C" },
          "amount": { "type": "string", "example": "10.00", "description": "USDT amount as a decimal string." },
          "walletPin": { "type": "string", "description": "PIN typed by the end user." },
          "protectedSymmetricKey": { "type": "string", "description": "Returned by `POST /api/wallet/keys`." }
        }
      },
      "WalletTransferResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "data": {
            "type": "object",
            "properties": {
              "txHash": { "type": "string" },
              "network": { "type": "string" },
              "recipientAddress": { "type": "string" },
              "asset": { "type": "string", "example": "USDT" },
              "amount": { "type": "string" }
            }
          }
        }
      },
      "WalletPayoutRequest": {
        "type": "object",
        "required": ["value", "network"],
        "properties": {
          "value": { "type": "integer", "minimum": 10, "example": 5000, "description": "BRL cents. Minimum 10 (R$ 0.10). There is no fixed maximum in the schema — the ceiling is your per-account per-transaction limit (`perTxLimitBrl`, default R$ 3000). Exceeding it returns 403 `PER_TX_LIMIT_EXCEEDED`." },
          "network": { "type": "string", "enum": ["polygon", "base", "tron"], "description": "Tron must additionally be enabled on the account (ask support)." },
          "asset": { "type": "string", "enum": ["USDT", "USDC", "BRLA"], "description": "Funding stablecoin. `polygon`: `USDT` (default) or `BRLA`. `base`: `USDC` (default) or `BRLA`. `tron`: `USDT` only." },
          "pixKey": { "type": "string" },
          "pixKeyType": { "$ref": "#/components/schemas/PixKeyType" },
          "qrCode": { "type": "string", "description": "PIX BR Code — mutually exclusive with `pixKey`." },
          "walletPin": { "type": "string" },
          "protectedSymmetricKey": { "type": "string" },
          "taxId": { "type": "string", "description": "CPF of the beneficiary receiving the PIX, digits only. Omit for the account holder. A different value is a third-party operation and returns 403 unless third-party operations are enabled for the account." },
          "subAccountId": { "type": "string", "description": "Pay out from this subaccount's wallet. `walletPin` and `protectedSymmetricKey` must be the subaccount's. Defaults to the main account." }
        }
      },
      "WalletPayoutResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "transactionId": { "type": "string", "example": "65f1a8..." },
          "status": { "type": "string", "example": "PROCESSING" },
          "stableAmount": { "type": "string", "example": "9.31" },
          "valueInBrl": { "type": "string", "example": "50.00" },
          "fee": { "type": "string", "example": "2.75" },
          "network": { "type": "string", "example": "polygon" },
          "jobId": { "type": "string" }
        }
      },
      "PayoutCreditParty": {
        "type": "object",
        "description": "Normalized credited-party details. CPF and account values remain masked; bank identifiers remain strings.",
        "properties": {
          "name": { "type": ["string", "null"] },
          "taxId": { "type": ["string", "null"], "description": "Masked CPF or formatted CNPJ." },
          "pixKey": { "type": ["string", "null"] },
          "pixKeyType": { "type": ["string", "null"] },
          "bankName": { "type": ["string", "null"] },
          "bankCode": { "type": ["string", "null"], "description": "Bank code when supplied, preserving leading zeros." },
          "ispb": { "type": ["string", "null"] },
          "branch": { "type": ["string", "null"] },
          "account": { "type": ["string", "null"], "description": "Account masked to the last four digits." },
          "accountType": { "type": ["string", "null"] }
        }
      },
      "PayoutReceipt": {
        "type": "object",
        "properties": {
          "endToEndId": { "type": ["string", "null"] },
          "paidAt": { "type": ["string", "null"], "format": "date-time" },
          "amountInBrl": { "type": "string" },
          "payerIspb": { "type": ["string", "null"] },
          "brCode": { "type": ["string", "null"] },
          "receiver": {
            "anyOf": [
              { "$ref": "#/components/schemas/PayoutCreditParty" },
              { "type": "null" }
            ]
          }
        }
      },
      "WalletPayoutStatusResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "data": {
            "type": "object",
            "properties": {
              "transactionId": { "type": "string" },
              "externalId": { "type": ["string", "null"] },
              "trackId": { "type": ["string", "null"] },
              "status": { "type": "string", "enum": ["PENDING", "COMPLETED", "FAILED", "REFUNDED"] },
              "asset": { "type": ["string", "null"] },
              "network": { "type": "string" },
              "txHash": { "type": "string", "nullable": true },
              "endToEndId": { "type": "string", "nullable": true },
              "valueInBrl": { "type": "string" },
              "fee": { "type": "string" },
              "pixKey": { "type": "string", "nullable": true },
              "qrCode": { "type": "string", "nullable": true },
              "provider": {
                "type": "string",
                "deprecated": true,
                "description": "Legacy documented field. Current responses may omit it."
              },
              "correlationID": {
                "type": ["string", "null"],
                "deprecated": true,
                "description": "Legacy documented field. Current responses may omit it."
              },
              "creditParty": {
                "anyOf": [
                  { "$ref": "#/components/schemas/PayoutCreditParty" },
                  { "type": "null" }
                ],
                "description": "Normalized credited-party details derived from a valid persisted receipt receiver; null until recipient details are available. This is not the raw provider payload."
              },
              "receipt": {
                "anyOf": [
                  { "$ref": "#/components/schemas/PayoutReceipt" },
                  { "type": "null" }
                ]
              },
              "receiptUrl": { "type": ["string", "null"], "format": "uri" },
              "receiptComplete": { "type": ["boolean", "null"] },
              "failureCode": { "type": ["string", "null"] },
              "failureReason": { "type": "string", "nullable": true },
              "createdAt": { "type": "string", "format": "date-time" },
              "updatedAt": { "type": "string", "format": "date-time" }
            }
          }
        }
      },
      "DepositAssetStatusResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "data": {
            "type": "object",
            "properties": {
              "externalId": { "type": "string" },
              "walletCharge": { "type": "string" },
              "trackId": { "type": "string", "nullable": true },
              "status": { "type": "string", "enum": ["PENDING", "FIAT_PAID", "PROCESSING", "COMPLETED", "FAILED", "EXPIRED", "REFUNDED"] },
              "errorCode": {"type": "string", "nullable": true},
              "errorDescription": {"type": "string", "nullable": true},
              "retryable": {"type": "boolean", "description": "True only after a full confirmed refund."},
              "refundStatus": {"type": "string", "nullable": true},
              "refundedValue": {"type": "integer", "nullable": true, "description": "Cumulative confirmed refunds, in BRL cents."},
              "refundedAt": {"type": "string", "format": "date-time", "nullable": true},
              "refundEndToEndId": {"type": "string", "nullable": true},
              "processingStep": { "type": "string", "nullable": true },
              "asset": { "type": "string" },
              "network": { "type": "string" },
              "address": { "type": "string" },
              "value": { "type": "integer", "description": "Amount in BRL cents." },
              "valueInBrl": { "type": "string" },
              "fee": { "type": "integer", "description": "Fee in BRL cents." },
              "feeInBrl": { "type": "string" },
              "fxRateAtTx": { "type": "number", "nullable": true },
              "receivedAmount": { "type": "integer", "nullable": true, "description": "Amount delivered, in the asset's smallest unit." },
              "receivedAmountDecimals": { "type": "integer", "nullable": true },
              "transactionHash": { "type": "string", "nullable": true },
              "qrCode": { "type": "string", "nullable": true },
              "endToEndId": { "type": "string", "nullable": true, "description": "End-to-end id of the PIX that funded the deposit." },
              "paidAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When the PIX settled." },
              "payer": {
                "type": "object",
                "nullable": true,
                "description": "Who paid the PIX. Only returned to accounts that own a virtual account.",
                "properties": {
                  "name": { "type": "string", "nullable": true },
                  "taxId": { "type": "string", "nullable": true, "description": "CPF/CNPJ of the payer, digits only." }
                }
              },
              "confirmedAt": { "type": "string", "format": "date-time", "nullable": true },
              "createdAt": { "type": "string", "format": "date-time" },
              "updatedAt": { "type": "string", "format": "date-time" }
            }
          }
        }
      },
      "AccountStatementResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "data": {
            "type": "object",
            "properties": {
              "balances": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "asset": { "type": "string" },
                    "network": { "type": "string", "nullable": true },
                    "amount": { "type": "string" }
                  }
                }
              },
              "operations": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": { "type": "string" },
                    "type": { "type": "string", "enum": ["DEPOSIT_ASSET", "PIX_OUT", "LIGHTNING_OUT", "WALLET_TRANSFER", "FEE"] },
                    "status": { "type": "string" },
                    "asset": { "type": "string" },
                    "network": { "type": "string" },
                    "valueInBrl": { "type": "string" },
                    "stableAmount": { "type": "string", "nullable": true },
                    "fee": { "type": "string" },
                    "txHash": { "type": "string", "nullable": true },
                    "endToEndId": { "type": "string", "nullable": true },
                    "createdAt": { "type": "string", "format": "date-time" },
                    "updatedAt": { "type": "string", "format": "date-time" }
                  }
                }
              },
              "page": { "type": "integer" },
              "pageSize": { "type": "integer" },
              "total": { "type": "integer" }
            }
          }
        }
      },
      "SubAccountCreateRequest": {
        "type": "object",
        "required": ["name"],
        "properties": {
          "name": { "type": "string", "minLength": 1, "maxLength": 64, "example": "Maria Silva" },
          "email": { "type": "string", "format": "email", "description": "Optional. Identifies the subaccount owner on KYC/KYB and in your statements. Omitting it no longer blocks later calls: the subaccount is always resolvable by `subAccountId`." },
          "accountType": { "type": "string", "enum": ["INDIVIDUAL", "COMPANY"], "default": "INDIVIDUAL" }
        }
      },
      "SubAccountListResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "data": {
            "type": "object",
            "properties": {
              "subAccounts": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "subAccountId": { "type": "string", "example": "883f2eec-0cea-44aa-9554-67055066bbc7" },
                    "email": { "type": "string", "example": "maria@example.com" },
                    "owner": { "type": "string", "enum": ["SELF", "CUSTOMER"] },
                    "createdAt": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          }
        }
      },
      "SubAccountCreateResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "data": {
            "type": "object",
            "properties": {
              "subAccountId": { "type": "string", "example": "883f2eec-0cea-44aa-9554-67055066bbc7" }
            }
          }
        }
      },
      "QuoteRequest": {
        "type": "object",
        "required": ["inputCurrency", "inputPaymentMethod", "outputCurrency", "outputPaymentMethod"],
        "description": "Pass exactly one of `inputAmount` or `outputAmount`.",
        "properties": {
          "inputCurrency": { "type": "string", "enum": ["BRL", "USDT", "USDC", "USDB", "BTC"] },
          "inputPaymentMethod": { "type": "string", "enum": ["PIX", "POLYGON", "BASE", "TRON", "LIGHTNING", "SPARK"] },
          "outputCurrency": { "type": "string", "enum": ["BRL", "USDT", "USDC", "USDB", "BTC"] },
          "outputPaymentMethod": { "type": "string", "enum": ["PIX", "POLYGON", "BASE", "TRON", "LIGHTNING", "SPARK"] },
          "inputAmount": { "type": "string", "example": "100.00", "description": "Decimal string." },
          "outputAmount": { "type": "string", "description": "Decimal string. Use for exact-out quotes." },
          "outputBrCode": { "type": "string", "description": "PIX BR Code, when the output goes to a known PIX recipient. Routes and prices this quote only — it grants no third-party permission." }
        }
      },
      "QuoteResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "data": {
            "type": "object",
            "properties": {
              "quoteToken": { "type": "string", "description": "Provider-side reference, returned for traceability. No Hodle endpoint accepts it as input — a quote is indicative pricing, not a rate lock." },
              "pairName": { "type": "string", "example": "BRL-USDC" },
              "basePrice": { "type": "string" },
              "inputCurrency": { "type": "string" },
              "outputCurrency": { "type": "string" },
              "inputAmount": { "type": "string" },
              "outputAmount": { "type": "string" },
              "inputAmountSats": { "type": "integer", "description": "BTC sats required by a BTC to BRL exact-output quote." },
              "outputAmountSats": { "type": "integer", "description": "BTC sats delivered by a BRL to BTC exact-input quote." },
              "feeInCents": { "type": "integer", "description": "Total fee charged to the authenticated API-key owner after custom fee overrides and floors." },
              "appliedFees": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "type": { "type": "string" },
                    "amount": { "type": "string" },
                    "currency": { "type": "string" }
                  }
                }
              },
              "expiresAt": { "type": "string", "format": "date-time", "description": "Two minutes after creation. Marks the price as stale, reserves nothing." }
            }
          }
        }
      },
      "KycCreateRequest": {
        "type": "object",
        "description": "Hosted flow. Omit `subAccountId` to run KYC for the API-key user itself.",
        "properties": {
          "subAccountId": { "type": "string", "description": "Subaccount the KYC belongs to." },
          "level": { "type": "string", "enum": ["LIGHT", "FULL"], "default": "FULL" },
          "redirectUrl": { "type": "string", "format": "uri", "description": "Where the customer lands once the hosted flow finishes." },
          "provider": { "type": "string", "enum": ["CARD", "DOCUMENTS", "HOSTED"], "description": "Available only when the card-first KYC order feature is enabled on your production account; ignored otherwise. Picks the verification step: `CARD`, then `DOCUMENTS`, then `HOSTED`, one at a time. Defaults to the active step, or the first open step when none has started. A later step may be requested to skip an earlier step that was never started; a closed step or a different provider while any verification is in progress answers `409`. See KYC > Card-first verification order." }
        }
      },
      "KycSubmitFormRequest": {
        "type": "object",
        "description": "Form flow, for integrators that collect the data and upload the documents themselves via `POST /api/kyc/document`. If the subaccount was created without an `email`, the one sent here becomes its email on file.",
        "required": ["subAccountId", "fullName", "dateOfBirth", "countryOfTaxId", "taxIdNumber", "email", "country", "state", "city", "zipCode", "streetAddress", "uploadedSelfieId", "uploadedDocumentId"],
        "properties": {
          "subAccountId": { "type": "string" },
          "fullName": { "type": "string" },
          "dateOfBirth": { "type": "string", "example": "1990-01-31", "description": "YYYY-MM-DD." },
          "countryOfTaxId": { "type": "string", "example": "BRA", "description": "ISO 3166-1 alpha-3." },
          "taxIdNumber": { "type": "string", "description": "Digits only." },
          "email": { "type": "string", "format": "email" },
          "phone": { "type": "string" },
          "country": { "type": "string", "example": "BRA", "description": "Must be `BRA` when Pods runs the KYC (as must `countryOfTaxId`); anything else answers `400` `KYC_PODS_INVALID_ADDRESS`." },
          "state": { "type": "string", "description": "Two-letter Brazilian state code (UF), e.g. `GO`; case is ignored. When Pods runs the KYC, anything else answers `400` `KYC_PODS_INVALID_ADDRESS`." },
          "city": { "type": "string" },
          "zipCode": { "type": "string", "description": "Brazilian CEP with 8 digits, with or without the hyphen (`75908-400` or `75908400`). When Pods runs the KYC, any other length answers `400` `KYC_PODS_INVALID_ADDRESS`." },
          "streetAddress": { "type": "string" },
          "uploadedSelfieId": { "type": "string", "description": "Document id returned by POST /api/kyc/document." },
          "uploadedDocumentId": { "type": "string", "description": "Document id returned by POST /api/kyc/document." }
        }
      },
      "KycCreateResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "data": {
            "type": "object",
            "properties": {
              "attemptId": { "type": "string", "nullable": true },
              "status": { "type": "string", "example": "PENDING" },
              "url": { "type": "string", "format": "uri", "nullable": true },
              "expiresAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Null when the provider does not publish an expiry for the hosted link." },
              "provider": { "type": "string", "enum": ["CARD", "DOCUMENTS", "HOSTED"], "description": "Card-first KYC order feature only: the verification step this answer opened. Absent without the feature." },
              "nextStep": { "type": "string", "nullable": true, "example": "POST /api/card/session", "description": "Card-first KYC order feature only: the call that continues the step (`POST /api/card/session` for `CARD`, `POST /api/kyc/document` for `DOCUMENTS`), or null when `url` or `attemptId` already is the next step." }
            }
          }
        }
      },
      "KycSubmitResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "data": {
            "type": "object",
            "properties": {
              "attemptId": { "type": "string" },
              "subAccountId": { "type": "string", "nullable": true, "description": "Subaccount the attempt belongs to." },
              "status": { "type": "string", "enum": ["PENDING", "APPROVED", "REJECTED"] },
              "linked": { "type": "boolean", "description": "Present (`true`) when the subaccount was linked to an existing verification." },
              "alreadySubmitted": { "type": "boolean", "description": "Present (`true`) when the same form was already submitted for this subaccount: the response is that attempt, with its current status." },
              "updatedAt": { "type": "string", "format": "date-time", "description": "Present with `alreadySubmitted`." },
              "rejectionReason": { "type": "string", "nullable": true, "description": "Present with `alreadySubmitted`: why the attempt was rejected, or `null`." },
              "createdAt": { "type": "string", "format": "date-time" }
            }
          }
        }
      },
      "KycImportTokenRequest": {
        "type": "object",
        "required": ["subAccountId", "importToken", "applicantId", "taxIdNumber", "email"],
        "properties": {
          "subAccountId": { "type": "string", "description": "INDIVIDUAL subaccount the verification is imported into." },
          "importToken": { "type": "string", "description": "Single-use Sumsub share token, minted for a GREEN applicant with the recipient `forClientId` support gives you. Never stored by Hodle." },
          "applicantId": { "type": "string", "description": "Id of the approved Sumsub applicant the token was minted for. Retrying with the same id returns the same attempt." },
          "taxIdNumber": { "type": "string", "example": "52998224725", "description": "The applicant's CPF, 11 digits (punctuation is ignored)." },
          "email": { "type": "string", "format": "email", "description": "The applicant's email." }
        }
      },
      "KycImportTokenResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "data": {
            "type": "object",
            "properties": {
              "attemptId": { "type": "string" },
              "subAccountId": { "type": "string" },
              "status": { "type": "string", "enum": ["PENDING", "APPROVED", "REJECTED"], "example": "PENDING" },
              "source": { "type": "string", "example": "SUMSUB_IMPORT" },
              "createdAt": { "type": "string", "format": "date-time" }
            }
          }
        }
      },
      "KycGetResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "data": {
            "type": "object",
            "properties": {
              "status": { "type": "string", "enum": ["NONE", "PENDING", "REVIEW", "APPROVED", "REJECTED", "EXPIRED", "FAILED"] },
              "level": { "type": "string", "enum": ["LIGHT", "FULL"] },
              "lastAttemptId": { "type": "string", "nullable": true },
              "approvedAt": { "type": "string", "format": "date-time", "nullable": true }
            }
          }
        }
      },
      "WebhookPayload": {
        "type": "object",
        "properties": {
          "event": {
            "type": "string",
            "enum": [
              "DEPOSIT_PIX_CONFIRMED",
              "DEPOSIT_ASSET_SUCCESS",
              "DEPOSIT_ASSET_FAILED",
              "DEPOSIT_ASSET_REFUNDED",
              "DEPOSIT_ONCHAIN_RECEIVED",
              "DEPOSIT_ON_HOLD",
              "PAYOUT_SUCCESSFUL",
              "PAYOUT_FAILED",
              "PAYOUT_ON_HOLD",
              "WALLET_TRANSFER_COMPLETED",
              "WALLET_TRANSFER_FAILED",
              "KYC_APPROVED",
              "KYC_REJECTED",
              "KYC_EXPIRED",
              "KYC_FAILED",
              "PAYOUT_REFUNDED",
              "DISPUTE_CREATED",
              "DISPUTE_ACCEPTED",
              "DISPUTE_REJECTED",
              "DISPUTE_CANCELED"
            ]
          },
          "data": {
            "type": "object",
            "additionalProperties": true,
            "description": "Event-specific payload. See the Webhooks guide for the shape per event."
          }
        }
      },
      "CardError": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string"
          },
          "errorCode": {
            "type": "string",
            "description": "Same value as `code`."
          },
          "stage": {
            "type": "string",
            "description": "The holder onboarding stage, on `CARD_NOT_ISSUED`."
          },
          "code": {
            "type": "string",
            "enum": [
              "CARD_PRODUCTION_ONLY",
              "CARD_NOT_ENABLED",
              "CARD_INVALID_REQUEST",
              "CARD_SESSION_REQUIRED",
              "CARD_NOT_ISSUED",
              "CARD_RATE_LIMITED",
              "CARD_REQUEST_FAILED",
              "CARD_NOT_FOUND",
              "SUBACCOUNT_NOT_FOUND",
              "SUBACCOUNT_NOT_INDIVIDUAL",
              "SUBACCOUNT_UNSUPPORTED",
              "SUBACCOUNT_EMAIL_REQUIRED",
              "SUBACCOUNT_TAX_ID_REQUIRED",
              "INVALID_PIN",
              "RATE_LIMITED",
              "WALLET_NOT_FOUND"
            ]
          }
        }
      },
      "CardStage": {
        "type": "string",
        "enum": [
          "AUTH_REQUIRED",
          "SIGN_UP",
          "TERMS",
          "KYC",
          "KYC_ACTION_REQUIRED",
          "SOURCE_OF_FUNDS",
          "PHONE",
          "SAFE",
          "CARD",
          "READY"
        ]
      },
      "CardOnboardingAction": {
        "type": "string",
        "enum": [
          "REQUEST_OTP",
          "SIGN_UP",
          "ACCEPT_TERMS",
          "START_KYC",
          "SUBMIT_SOURCE_OF_FUNDS",
          "REQUEST_PHONE_CODE",
          "VERIFY_PHONE",
          "DEPLOY_SAFE",
          "ISSUE_VIRTUAL_CARD"
        ]
      },
      "CardStatus": {
        "type": "object",
        "properties": {
          "stage": {
            "$ref": "#/components/schemas/CardStage"
          },
          "registered": {
            "type": "boolean"
          },
          "termsAccepted": {
            "type": "boolean"
          },
          "kycStatus": {
            "type": "string",
            "enum": [
              "NOT_STARTED",
              "PENDING",
              "ACTION_REQUIRED",
              "APPROVED",
              "REJECTED"
            ],
            "description": "`REJECTED` is terminal."
          },
          "kycUrl": {
            "type": "string",
            "nullable": true,
            "description": "Hosted identity check for the holder, returned by `START_KYC`."
          },
          "sourceOfFundsAnswered": {
            "type": "boolean"
          },
          "phoneValidated": {
            "type": "boolean"
          },
          "safeDeployed": {
            "type": "boolean"
          },
          "safeAddress": {
            "type": "string",
            "nullable": true
          },
          "activeCardCount": {
            "type": "integer"
          },
          "terms": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string"
                },
                "currentVersion": {
                  "type": "string"
                },
                "accepted": {
                  "type": "boolean"
                },
                "url": {
                  "type": "string",
                  "nullable": true
                }
              }
            }
          },
          "sourceOfFundsQuestions": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "question": {
                  "type": "string"
                },
                "answers": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "nextStep": {
            "type": "object",
            "properties": {
              "actions": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/CardOnboardingAction"
                }
              },
              "humanStep": {
                "type": "string",
                "nullable": true,
                "enum": [
                  "SIGN_IN",
                  "EMAIL_CODE",
                  "HOSTED_KYC",
                  "SOURCE_OF_FUNDS_ANSWERS",
                  "SMS_CODE",
                  null
                ]
              }
            }
          }
        }
      },
      "Card": {
        "type": "object",
        "description": "Never carries the card number, CVV or expiry.",
        "properties": {
          "cardId": {
            "type": "string",
            "description": "Opaque card id."
          },
          "lastFourDigits": {
            "type": "string",
            "example": "4242"
          },
          "virtual": {
            "type": "boolean"
          },
          "statusCode": {
            "type": "integer",
            "description": "`1000` is active."
          },
          "activatedAt": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "CardBalance": {
        "type": "object",
        "nullable": true,
        "properties": {
          "currency": {
            "type": "string",
            "example": "USDC"
          },
          "total": {
            "type": "string",
            "nullable": true
          },
          "spendable": {
            "type": "string",
            "nullable": true
          },
          "pending": {
            "type": "string",
            "nullable": true
          },
          "onChain": {
            "type": "string",
            "nullable": true
          },
          "requiresAuthentication": {
            "type": "boolean"
          },
          "checkedAt": {
            "type": "string"
          }
        }
      },
      "CardFunding": {
        "type": "object",
        "properties": {
          "fundingId": {
            "type": "string",
            "format": "uuid"
          },
          "subAccountId": {
            "type": "string",
            "nullable": true
          },
          "status": {
            "type": "string",
            "enum": [
              "QUOTED",
              "SUBMITTING",
              "PENDING",
              "COMPLETED",
              "FAILED",
              "RECONCILIATION_REQUIRED"
            ]
          },
          "sourceKey": {
            "type": "string"
          },
          "amount": {
            "type": "string"
          },
          "expectedAmount": {
            "type": "string"
          },
          "minimumAmount": {
            "type": "string"
          },
          "nativeFee": {
            "type": "string"
          },
          "feeUsd": {
            "type": "string"
          },
          "durationSeconds": {
            "type": "integer"
          },
          "expiresAt": {
            "type": "string"
          },
          "signingHash": {
            "type": "string",
            "description": "Sign as a raw digest with the EOA of `signingWalletId`."
          },
          "signingWalletId": {
            "type": "string"
          },
          "txHash": {
            "type": "string",
            "nullable": true
          },
          "receivingTxHash": {
            "type": "string",
            "nullable": true
          }
        }
      }
    }
  },
  "paths": {
    "/api/subaccount": {
      "post": {
        "operationId": "subAccountCreate",
        "summary": "Create a subaccount",
        "description": "Create an end-user subaccount under your API key. Subaccounts are permanent — deletion is not supported. Pass `email` so later KYC/KYB and operation calls can resolve it.",
        "tags": ["Subaccounts"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/SubAccountCreateRequest" }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Subaccount created.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SubAccountCreateResponse" }
              }
            }
          },
          "400": {
            "description": "Validation failed or the request was rejected upstream.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          },
          "401": {
            "description": "Missing key, or key does not match the base URL environment.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      },
      "get": {
        "operationId": "subAccountList",
        "summary": "List your subaccounts",
        "tags": ["Subaccounts"],
        "responses": {
          "200": {
            "description": "Subaccounts scoped to your API key: your own Avenia subaccount (`owner: SELF`) plus the ones you created for customers (`owner: CUSTOMER`).",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SubAccountListResponse" }
              }
            }
          },
          "401": {
            "description": "Missing key, or key does not match the base URL environment.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      }
    },
    "/api/subaccount/{subAccountId}": {
      "get": {
        "operationId": "subAccountGet",
        "summary": "Read one subaccount",
        "tags": ["Subaccounts"],
        "parameters": [
          { "name": "subAccountId", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Subaccount detail." },
          "404": {
            "description": "Not found, or not scoped to your API key.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      }
    },
    "/api/quote": {
      "post": {
        "operationId": "quote",
        "summary": "Price a BRL ↔ asset conversion",
        "description": "Indicative pricing and fee breakdown for a pair. The returned `quoteToken` is informational — no endpoint consumes it, so a quote does not lock a rate. Price the operation immediately before executing it.",
        "tags": ["Pricing"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/QuoteRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Quote.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/QuoteResponse" }
              }
            }
          },
          "400": {
            "description": "Validation failed, amount below minimum, or pair not routable.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      }
    },
    "/api/kyc": {
      "get": {
        "operationId": "kycGet",
        "summary": "Get current KYC state",
        "description": "State of the API-key user, or of one subaccount when `subAccountId` is given. Answers `200` with `status: NONE` when nothing was ever submitted.",
        "tags": ["KYC"],
        "parameters": [
          { "name": "subAccountId", "in": "query", "schema": { "type": "string" }, "description": "Read the state of this subaccount instead of the API-key user." }
        ],
        "responses": {
          "200": {
            "description": "KYC state.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/KycGetResponse" }
              }
            }
          },
          "404": { "description": "Subaccount not found for this platform." }
        }
      },
      "post": {
        "operationId": "kycCreate",
        "summary": "Start a KYC attempt",
        "description": "Two payloads are accepted on this route. Send `{ level, redirectUrl }` (optionally `subAccountId`) to open the **hosted flow** — the response carries the `url` the customer must visit. Send the **form payload** (`KycSubmitFormRequest`) when you collect and upload the documents yourself; it answers `202` with the attempt id instead of a url.",
        "tags": ["KYC"],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  { "$ref": "#/components/schemas/KycCreateRequest" },
                  { "$ref": "#/components/schemas/KycSubmitFormRequest" }
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Hosted KYC attempt created. Send the customer to `data.url`.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/KycCreateResponse" }
              }
            }
          },
          "200": {
            "description": "Form payload: the person behind `taxIdNumber` is already verified at Hodle: the subaccount is linked to that verification and `KYC_APPROVED` (with `linked: true`) is sent before this response. Hosted payload with the card-first KYC order feature: the `CARD` or `DOCUMENTS` step is open (`KycCreateResponse` with `provider`, `nextStep`, and `attemptId` null unless a documents attempt is already running); no attempt is created.",
            "content": { "application/json": { "schema": { "oneOf": [{ "$ref": "#/components/schemas/KycSubmitResponse" }, { "$ref": "#/components/schemas/KycCreateResponse" }] } } }
          },
          "202": {
            "description": "Form submission accepted. Poll `GET /api/kyc/{attemptId}` for the result. Sending the same form again for the same subaccount (same `uploadedDocumentId` and `uploadedSelfieId`) is idempotent: it opens nothing new and answers `202` with the attempt it already opened, its current `status`, `updatedAt`, `rejectionReason` and `alreadySubmitted: true`.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KycSubmitResponse" } } }
          },
          "400": { "description": "Validation error. When Pods runs the KYC the body is `{ success: false, error: \"Validation failed\", code: \"KYC_PODS_INVALID_ADDRESS\", details: [{ field, message }] }` for an address Pods cannot take (see `zipCode`, `state`, `country` and `countryOfTaxId` of `KycSubmitFormRequest`). Nothing is submitted, so the uploaded document ids stay valid for the corrected retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "401": { "description": "Unauthorized." },
          "409": { "description": "Form payload: `code: KYC_DOCUMENT_ALREADY_USED` when `uploadedDocumentId` or `uploadedSelfieId` was already used by another KYC submission (another subaccount, or a different pair of documents): `{ success: false, error: \"uploadedDocumentId already used by another KYC submission\", code: \"KYC_DOCUMENT_ALREADY_USED\" }`. Upload new documents for a new submission. `code: KYC_PROVIDER_REJECTED` when the provider already rejected the person behind the subaccount. Card-first KYC order feature only: the requested `provider` is not open. Body `{ success: false, error, code, currentProvider }`, where `code` is `PROVIDER_STEP_IN_PROGRESS` (another provider is still running) or `PROVIDER_NOT_AVAILABLE` (the step was rejected or is not available to the account) and `currentProvider` names the open step.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/kyc/import-token": {
      "post": {
        "operationId": "kycImportToken",
        "summary": "Import an existing Sumsub verification",
        "description": "Reuse a KYC you already ran on your own Sumsub account instead of verifying the user again. Mint a single-use share token for the recipient `forClientId` support gives you, and post it with the applicant id, CPF and email. A `202` means the token was accepted; `status` is `APPROVED` right away when the identity was approved before, otherwise poll `GET /api/kyc/{attemptId}` or wait for the `KYC_APPROVED` / `KYC_REJECTED` webhook. Posting again for the same `applicantId` returns the same attempt.",
        "tags": ["KYC"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/KycImportTokenRequest" }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Token accepted for processing. Poll `GET /api/kyc/{attemptId}` for the result.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/KycImportTokenResponse" }
              }
            }
          },
          "400": { "description": "Missing token, or a token the provider refused (`errorCode`: `INVALID_IMPORT_TOKEN`, `IMPORT_FAILED`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "401": { "description": "Unauthorized." },
          "404": { "description": "Subaccount not found for this platform." },
          "409": { "description": "Token already consumed, or `taxIdNumber` differs from the one already imported for this `applicantId` (`errorCode`: `IMPORT_TOKEN_ALREADY_USED`, `TAX_ID_MISMATCH`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "502": { "description": "Temporary failure importing the verification; retry with a new token (`errorCode`: `IMPORT_FAILED`, `IMPORT_NOT_ENABLED`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/account/statement": {
      "get": {
        "operationId": "accountStatement",
        "summary": "Account statement",
        "description": "Returns balances per asset and a paginated list of operations. Requires full KYC.",
        "tags": ["Account"],
        "parameters": [
          { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "ISO date/datetime. Defaults to 30 days ago." },
          { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "ISO date/datetime. Defaults to now. Window must be at most 90 days." },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "maximum": 200, "default": 50 }, "description": "Max operations per page." },
          { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor from a previous response's nextCursor." },
          { "name": "type", "in": "query", "schema": { "type": "array", "items": { "type": "string", "enum": ["deposit", "withdraw", "payout", "transfer"] } }, "description": "Filter by operation type. Repeat the param to pass multiple." },
          { "name": "subAccountId", "in": "query", "schema": { "type": "string" }, "description": "Read the statement of one of your sub-accounts (its wallets and operations). 404 if the sub-account is not yours." }
        ],
        "responses": {
          "200": {
            "description": "Statement.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/AccountStatementResponse" }
              }
            }
          },
          "403": { "description": "Full KYC required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/wallet": {
      "get": {
        "operationId": "walletGet",
        "summary": "Read a wallet",
        "description": "Returns the addresses per network and current balances of the API-key user, or of one subaccount when `subAccountId` is given. `POST /api/wallet/get` serves the same payload with the fields in the body. An explicit walletId scopes the response to that wallet.",
        "tags": [
          "Wallet"
        ],
        "parameters": [
          {
            "name": "subAccountId",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Read this subaccount's wallet instead of the API-key user's."
          },
          {
            "name": "walletId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[a-fA-F0-9]{24}$"
            },
            "description": "Exact wallet ID scoped by owner and subAccountId. Unknown or foreign IDs return 404."
          }
        ],
        "responses": {
          "200": {
            "description": "Wallet.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WalletGetResponse"
                }
              }
            }
          },
          "404": {
            "description": "Wallet not provisioned. With `subAccountId`, an owned sub-account that has no wallet yet answers `404` with `errorCode: SUBACCOUNT_WALLET_NOT_PROVISIONED` (`error`: \"Sub-account has no wallet yet: wallets are created when its KYC is approved\"). Sub-account wallets are created by its KYC approval: wait for `KYC_APPROVED` (or `GET /api/kyc?subAccountId=`) before reading it. An unknown sub-account keeps `Subaccount not found for this platform` without `errorCode`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Sub-account has no wallet yet: wallets are created when its KYC is approved" }, "errorCode": { "type": "string", "enum": ["SUBACCOUNT_WALLET_NOT_PROVISIONED"] } } } } }
          }
        }
      }
    },
    "/api/wallet/keys": {
      "post": {
        "tags": [
          "wallet"
        ],
        "summary": "Get the user's protected symmetric key",
        "description": "Returns the wallet's `protectedSymmetricKey` and the user's `email`. These\nvalues are required to derive the `symmetricKey` client-side before\ncalling `/api/wallet/payout`.\n\n**Requires API payouts enabled on the account (ask support).** Without it\nthe endpoint responds `403`.\n\nPass `subAccountId` to read a customer sub-account's wallet instead of\nyour own. Without it the endpoint answers for the API key owner. The\n`email` returned is always the one that derives the key for the wallet\nbeing read, so use exactly the pair this endpoint returns together.\n\n**Aggressive rate limit: 1 request per minute**, counted per wallet — your\nown and each sub-account get their own window. Cache the response in your\ndatabase — these values only change if the user resets their PIN.\n",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "in": "query",
            "name": "walletId",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[a-fA-F0-9]{24}$"
            },
            "description": "Exact wallet ID from wallet/create, scoped by owner and subAccountId. Also accepted in the JSON body. No fallback on an invalid reference."
          },
          {
            "in": "query",
            "name": "subAccountId",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Sub-account whose wallet key is returned. Must be a sub-account your\nAPI key created; any other id answers `404`. May also be sent in the\nJSON body.\n",
            "example": "be1424d8-0000-0000-0000-000000000000"
          }
        ],
        "responses": {
          "200": {
            "description": "Returns the protected symmetric key and email",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "walletId": {
                          "type": "string",
                          "description": "Selected wallet ID. Cache the protected key per walletId."
                        },
                        "protectedSymmetricKey": {
                          "type": "string",
                          "description": "NIP-44 encrypted symmetric key (base64). Decrypt with PIN-derived masterKey.",
                          "example": "AoofiKHyVRLvdrknnXzo..."
                        },
                        "email": {
                          "type": "string",
                          "description": "Email that salts the Argon2id masterKey derivation for this wallet.",
                          "example": "user@example.com"
                        },
                        "subAccountId": {
                          "type": "string",
                          "nullable": true,
                          "description": "Sub-account this key belongs to, or `null` for your own wallet.",
                          "example": "be1424d8-0000-0000-0000-000000000000"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized (missing or invalid API key)"
          },
          "403": {
            "description": "API payouts are not enabled on the account (ask support)"
          },
          "404": {
            "description": "Wallet not found or has no protected symmetric key. With `subAccountId`, an owned sub-account that has no wallet yet answers `404` with `errorCode: SUBACCOUNT_WALLET_NOT_PROVISIONED` (`error`: \"Sub-account has no wallet yet: wallets are created when its KYC is approved\"). Sub-account wallets are created by its KYC approval: wait for `KYC_APPROVED` (or `GET /api/kyc?subAccountId=`) before reading it. An unknown sub-account keeps `Subaccount not found for this platform` without `errorCode`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Sub-account has no wallet yet: wallets are created when its KYC is approved" }, "errorCode": { "type": "string", "enum": ["SUBACCOUNT_WALLET_NOT_PROVISIONED"] } } } } }
          },
          "429": {
            "description": "Too many requests",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds until next allowed request"
              }
            }
          }
        }
      }
    },
    "/api/wallet/transfer": {
      "post": {
        "tags": [
          "wallet"
        ],
        "summary": "Transfer a stablecoin on Polygon, Base or Solana to an internal or external address",
        "description": "Transfers a token from the authenticated user's wallet. On Polygon and\nBase the server signs and submits an ERC-4337 UserOp (gas sponsored) from\nthe user's smart account. On Solana the server signs an SPL\n`transferChecked` with the user's Solana keypair and Hodler's master\nwallet pays the network fee (and the rent of the recipient's associated\ntoken account when it does not exist yet).\n\nThe recipient can be:\n  - an **external address** via `recipientAddress` — a checksummed EVM\n    address on `polygon`/`base`, a base58 address on `solana`. The\n    destination does not need to be a Hodler wallet.\n  - an **internal linked user** via `toSubAccountId` or `toUserId`\n    (must be linked to the same platform account). The recipient's\n    address is resolved on the same network as the request.\n\nRequires `walletPin` + `protectedSymmetricKey` (fetch the latter via\n`POST /api/wallet/keys`).\n\n**Requires API payouts enabled on the account (ask support).** Without it\nthe endpoint responds `403`.\n\n**Asset selection:** the optional `asset` field defaults to `USDT` and\nthe optional `network` field defaults to `polygon`. Supported pairs:\n\n| network  | assets              |\n|----------|---------------------|\n| polygon  | USDT, USDC, BRLA    |\n| base     | USDC, BRLA          |\n| solana   | USDT, USDC, BRS     |\n\nOnly `USDT` on Polygon debits the internal USDT ledger (balance is\nchecked server-side). Every other pair is enforced on-chain — the\ntransaction fails if the wallet lacks funds.\n\n**BRS must be enabled on the account** (ask support).\nWithout it the endpoint responds `403`.\n\n**Completion webhook:** every transfer that returns a\n`transactionId` sends `WALLET_TRANSFER_COMPLETED` once confirmed\non-chain, or `WALLET_TRANSFER_FAILED` when a `202` transfer never lands.\nSee /docs/webhooks#wallet-transfer-events.\n",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "amount",
                  "walletPin",
                  "protectedSymmetricKey"
                ],
                "properties": {
                  "recipientAddress": {
                    "type": "string",
                    "description": "Destination address (external or internal). Mutually\nexclusive with `toSubAccountId` / `toUserId`. Must be a valid\nchecksummed EVM address on `polygon`/`base`, or a valid\nbase58 address on `solana`.\n",
                    "example": "0x520ec4aD3BdC629D13a49dB558D7F6813f3696aD"
                  },
                  "toSubAccountId": {
                    "type": "string",
                    "description": "Sub-account id of a linked internal recipient. Resolves to\nthat user's wallet address.\n"
                  },
                  "toUserId": {
                    "type": "string",
                    "description": "User id of a linked internal recipient (must share the same\nlinked platform account).\n"
                  },
                  "fromSubAccountId": {
                    "type": "string",
                    "description": "Optional source sub-account. When omitted the transfer debits\nthe authenticated application user's own wallet.\n"
                  },
                  "amount": {
                    "type": "string",
                    "description": "Token amount to send. Min above 0, max 10000.",
                    "example": "50"
                  },
                  "network": {
                    "type": "string",
                    "enum": [
                      "polygon",
                      "base",
                      "solana"
                    ],
                    "default": "polygon",
                    "description": "Network the transfer runs on.",
                    "example": "solana"
                  },
                  "asset": {
                    "type": "string",
                    "enum": [
                      "USDT",
                      "USDC",
                      "BRLA",
                      "BRS"
                    ],
                    "default": "USDT",
                    "description": "Token to transfer. Defaults to `USDT`. Only `USDT` on Polygon\ntouches the internal ledger; every other pair relies on the\non-chain balance. `BRS` is Solana-only and must be\nenabled on the account (ask support).\n",
                    "example": "BRS"
                  },
                  "reference": {
                    "type": "string",
                    "description": "Optional idempotency key. A retry with a reference that was\nalready used never sends again: it answers `409` with the\noriginal `transactionId`, `status` and `txHash`. A reference\nis released only when the first attempt failed before\nanything was sent. Without a reference a repeated call is a\nnew transfer.\n",
                    "example": "order-9f3c1a"
                  },
                  "walletId": {
                    "type": "string",
                    "pattern": "^[a-fA-F0-9]{24}$",
                    "description": "ID returned by wallet/create. Selects the exact spending wallet within the source owner/subaccount scope, with no fallback. Use its protectedSymmetricKey. For signature-based payouts, use only on the prepare request; payoutIntentId selects the wallet on submission."
                  },
                  "walletPin": {
                    "type": "string",
                    "description": "User's wallet PIN. Combined with email + protectedSymmetricKey\nto derive the symmetricKey server-side via Argon2id.\n",
                    "example": "1234"
                  },
                  "protectedSymmetricKey": {
                    "type": "string",
                    "description": "NIP-44 encrypted symmetric key. Get from `POST /api/wallet/keys`.",
                    "example": "AoofiKHyVRLvdrknnXzo..."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Transfer submitted and confirmed on-chain.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "txHash": {
                          "type": "string",
                          "example": "0xd3c1b3c6de23381ffa51ceae0712190a9406b939e5a33e2c25af0a37cb599be1"
                        },
                        "senderAddress": {
                          "type": "string",
                          "example": "0x369C5850F85ceAe372a34AD3Df1f6568289ec0D1"
                        },
                        "recipientAddress": {
                          "type": "string",
                          "example": "0x520ec4aD3BdC629D13a49dB558D7F6813f3696aD"
                        },
                        "amount": {
                          "type": "string",
                          "example": "50"
                        },
                        "asset": {
                          "type": "string",
                          "enum": [
                            "USDT",
                            "USDC",
                            "BRLA",
                            "BRS"
                          ],
                          "example": "BRS"
                        },
                        "transactionId": {
                          "type": "string",
                          "example": "65f1a8..."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation failure, invalid recipient address, invalid PIN, or\ninsufficient USDT ledger balance (USDT only).\n",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "error": {
                      "type": "string",
                      "example": "Invalid recipient address"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "The source account is blocked, API payouts are not\nenabled on the account, or the requested asset is not enabled on\nthe account (ask support).\n"
          },
          "429": {
            "description": "Rate limit hit (30s/user)."
          }
        }
      }
    },
    "/api/wallet/payout": {
      "post": {
        "tags": [
          "wallet"
        ],
        "summary": "Pay PIX from a wallet balance on Polygon, Base, Tron or Solana",
        "description": "Initiates a wallet → PIX payout. The server signs and submits\nthe on-chain UserOp on behalf of the user, then triggers PIX cashout\nin the background.\n\n**Returns immediately (HTTP 202).** Poll `GET /api/wallet/payout/{transactionId}`\nto track status.\n\nA request retried with the same `externalId` returns HTTP 200 with\n`alreadyProcessed: true` and the original `transactionId`.\n\nRequires `walletPin` + `protectedSymmetricKey` (fetch the latter via\n`POST /api/wallet/keys`).\n\n**Requires API payouts enabled on the account (ask support).** Without it\nthe endpoint responds `403`.\n\nSupported network/asset pairs (`asset` is optional and uses the ordered\npreference shown below):\n\n| network  | assets            | automatic order       | debit destination            |\n|----------|-------------------|-----------------------|------------------------------|\n| polygon  | USDT, USDC, BRLA  | BRLA, then USDT, USDC | Avenia sub-account or master |\n| base     | USDC, BRLA        | BRLA, then USDC        | Avenia sub-account or master |\n| tron     | USDT (forced)     | USDT                  | Avenia Tron deposit address  |\n| solana   | USDT, USDC, BRS   | USDT, then USDC        | Hodler master Solana wallet  |\n\n**BRLA is tried first because direct USD-stablecoin liquidation has a\nhigher provider cost.** If BRLA cannot cover the complete debit — payout\nvalue plus the fee for BRLA — the server tries the next supported asset\ndirectly. It never performs USDC → BRLA → PIX as an intermediate swap.\nThere is no partial BRLA + USDC debit: one asset must cover the complete\namount. An explicit `asset: BRLA` has the same preference behavior. On\nPolygon/Base, an explicit USDC/USDT request selects that asset as the\ndirect fallback; on Solana, where BRLA is unavailable, the requested\nUSDC/USDT/BRS is debited directly. Fallback happens only when the balance\ncheck fails before signing; once a payout is prepared or processing, no\nsecond asset is attempted.\n\nOn Solana the server signs an SPL `transferChecked` with the user's Solana\nkeypair and Hodler's master wallet pays the network fee. Avenia has no\nSolana deposit address, so the debit lands on Hodler's master Solana\nwallet and the PIX leg is settled from the float.\n\n**BRS must be enabled on the account** (ask support);\nwithout it the endpoint responds `403`. BRS is BRL-pegged, so\nit is debited 1:1 with the BRL amount instead of going through the FX\nrate, and the PIX leg draws on the BRLA float.\n\n**Tron must be enabled on the account (ask support).**\n",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "value",
                  "network",
                  "walletPin",
                  "protectedSymmetricKey"
                ],
                "properties": {
                  "value": {
                    "type": "integer",
                    "description": "Amount in BRL cents. Min 10. Max is the user per-tx limit (`perTxLimitBrl`, default R$ 3000).",
                    "example": 5000
                  },
                  "network": {
                    "type": "string",
                    "enum": [
                      "polygon",
                      "base",
                      "tron",
                      "solana"
                    ],
                    "description": "Source network the stablecoin debit runs on.",
                    "example": "solana"
                  },
                  "asset": {
                    "type": "string",
                    "enum": [
                      "USDT",
                      "USDC",
                      "BRLA",
                      "BRS"
                    ],
                    "description": "Stablecoin preference to debit. Optional — tries the automatic\norder shown in the table above. `BRLA` may fall back to the\nnext supported direct asset when the full debit cannot fit.\nOn Polygon/Base, explicit USDC/USDT is the direct fallback;\non Solana they are debited directly because BRLA is not\nsupported. Ignored on `tron`, which always debits USDT.\n`BRS` is Solana-only and must be enabled on the account (ask support).\n",
                    "example": "BRS"
                  },
                  "pixKey": {
                    "type": "string",
                    "description": "PIX key of the recipient. Mutually exclusive with qrCode.",
                    "example": "recipient@example.com"
                  },
                  "pixKeyType": {
                    "type": "string",
                    "enum": [
                      "PHONE",
                      "CPF",
                      "EMAIL",
                      "RANDOM",
                      "CNPJ"
                    ],
                    "description": "Required when pixKey is provided.",
                    "example": "EMAIL"
                  },
                  "qrCode": {
                    "type": "string",
                    "description": "PIX BR Code copy-paste. Mutually exclusive with pixKey."
                  },
                  "walletId": {
                    "type": "string",
                    "pattern": "^[a-fA-F0-9]{24}$",
                    "description": "ID returned by wallet/create. Selects the exact spending wallet within the source owner/subaccount scope, with no fallback. Use its protectedSymmetricKey. For signature-based payouts, use only on the prepare request; payoutIntentId selects the wallet on submission."
                  },
                  "walletPin": {
                    "type": "string",
                    "description": "User's wallet PIN. Combined with email + protectedSymmetricKey\nto derive the symmetricKey server-side via Argon2id.\n",
                    "example": "1234"
                  },
                  "protectedSymmetricKey": {
                    "type": "string",
                    "description": "NIP-44 encrypted symmetric key. Get from `POST /api/wallet/keys`.",
                    "example": "AoofiKHyVRLvdrknnXzo..."
                  },
                  "externalId": {
                    "type": "string",
                    "description": "Optional caller-provided idempotency key. A repeated request\nwith the same externalId returns the original payout as\n`alreadyProcessed`, even after the heuristic window expires.\nDifferent externalIds are treated as separate payout orders\nand bypass the short-window duplicate heuristic. Without an\nexternalId, requests with the same user, value and PIX key\nmay be deduplicated heuristically for a short window.\n",
                    "example": "offramp:order-9f3c1a"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Existing payout returned for an idempotent retry.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "success",
                    "alreadyProcessed",
                    "transactionId",
                    "status"
                  ],
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "alreadyProcessed": {
                      "type": "boolean",
                      "example": true
                    },
                    "transactionId": {
                      "type": "string",
                      "example": "65f1a8..."
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "PENDING",
                        "COMPLETED",
                        "FAILED",
                        "REFUNDED"
                      ]
                    },
                    "txHash": {
                      "type": "string",
                      "nullable": true
                    }
                  }
                }
              }
            }
          },
          "202": {
            "description": "Payout queued. Poll the GET endpoint for status.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "transactionId": {
                      "type": "string",
                      "example": "65f1a8..."
                    },
                    "externalId": {
                      "type": "string",
                      "nullable": true,
                      "description": "The idempotency key sent in the request, echoed back.",
                      "example": "offramp:823e6356"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "PROCESSING"
                      ]
                    },
                    "stableAmount": {
                      "type": "string",
                      "description": "USDT/USDC amount that will be transferred.",
                      "example": "9.31"
                    },
                    "valueInBrl": {
                      "type": "string",
                      "example": "50.00"
                    },
                    "fee": {
                      "type": "string",
                      "example": "1.55"
                    },
                    "network": {
                      "type": "string",
                      "example": "solana"
                    },
                    "asset": {
                      "type": "string",
                      "enum": [
                        "USDT",
                        "USDC",
                        "BRLA",
                        "BRS"
                      ],
                      "example": "BRS"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation failure, invalid PIN, or insufficient balance",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "error": {
                      "type": "string",
                      "example": "Invalid PIN"
                    },
                    "errorCode": {
                      "type": "string",
                      "enum": [
                        "INVALID_PIN",
                        "RATE_LIMITED",
                        "WALLET_NOT_FOUND",
                        "PREPARE_FAILED",
                        "INSUFFICIENT_BALANCE"
                      ],
                      "example": "INSUFFICIENT_BALANCE"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "The user account is blocked, API payouts are not\nenabled on the account, a per-tx/total limit was\nexceeded, or the requested asset is not enabled on the account\n(ask support).\n"
          },
          "409": {
            "description": "WALLET_BUSY: payouts of one wallet and network are signed one at a time, in arrival order; this one waited more than 25s for the wallet's earlier payouts to land (or one of them is still being confirmed on-chain). Nothing is created. Retry a few seconds later, or once `blockingTransactionId` has a txHash (`retryable: true`).",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          },
          "429": {
            "description": "Rate limit hit (30s/user) or 3 invalid PIN attempts → 24h lock"
          },
          "503": {
            "description": "PIX payments temporarily disabled"
          }
        }
      }
    },
    "/api/wallet/payout/{transactionId}": {
      "get": {
        "operationId": "walletPayoutStatus",
        "summary": "Get payout status",
        "tags": ["Wallet"],
        "parameters": [
          { "name": "transactionId", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Status.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/WalletPayoutStatusResponse" }
              }
            }
          }
        }
      }
    },
    "/api/deposit/asset": {
      "post": {
        "operationId": "depositAsset",
        "summary": "Create a deposit (PIX → crypto)",
        "description": "Convert BRL to Lightning, USDT, USDC, or USDCE and deliver to an address. Requires full KYC.",
        "tags": ["Deposits"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/DepositAssetRequest" },
              "examples": {
                "lightning": {
                  "summary": "Lightning deposit",
                  "value": { "value": 5000, "address": "lnbc500u1pj...", "asset": "LIGHTNING", "externalId": "order-001" }
                },
                "usdt": {
                  "summary": "USDT (Polygon) deposit",
                  "value": { "value": 25000, "asset": "USDT", "network": "polygon", "address": "0x9aB7a1..." }
                },
                "usdc": {
                  "summary": "USDC (Base) deposit",
                  "value": { "value": 25000, "asset": "USDC", "network": "base", "address": "0x9aB7a1..." }
                },
                "usdcSolana": {
                  "summary": "USDC (Solana) deposit to an external wallet",
                  "description": "Settled on Base and bridged to the Solana address by Hodle; the bridge cost is taken on delivery, so slightly less than the quoted amount lands. Solana delivery must be enabled on the account.",
                  "value": { "value": 5000, "asset": "USDC", "network": "solana", "address": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM", "externalId": "order-2041" }
                },
                "externalWalletDeclaration": {
                  "summary": "BRLA (Polygon) to a new external wallet with a wallet declaration (ACAM)",
                  "description": "First deposit to an external wallet held outside Brazil: walletDeclaration with purposeCode. A holder in Brazil sends counterpartyCountry BR and no purposeCode. See /docs/wallet-declaration.",
                  "value": { "value": 50000, "asset": "BRLA", "network": "polygon", "address": "0x4444444444444444444444444444444444444444", "externalId": "order-3001", "walletDeclaration": { "isSelfCustody": true, "counterpartyName": "Example Holdings LLC", "counterpartyCountry": "US", "reason": "Purchase of virtual assets for the company treasury", "purposeCode": "91992" } }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Deposit created.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/DepositAssetResponse" }
              }
            }
          },
          "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "403": { "description": "Full KYC required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "409": { "description": "The `externalId` is already used by a deposit that is not yours. Nothing is created; retry with a different `externalId`. Repeating your own `externalId` answers 200 with the original deposit instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "429": { "description": "Rate limit exceeded: 60 requests per minute per API key across all routes. Honor the `Retry-After` header." }
        }
      }
    },
    "/api/deposit/{id}": {
      "get": {
        "operationId": "depositGet",
        "summary": "Get deposit status by walletCharge, trackId or externalId",
        "description": "Polls a deposit by any id you hold for it: the `walletCharge` returned by the POST, the `trackId` sent on every webhook, or your own `externalId`. Same response as `GET /api/deposit/asset/{externalId}`. The deposit twin of `GET /api/wallet/payout/{transactionId}`. Poll every 5s while `status` is `PENDING`, `FIAT_PAID` or `PROCESSING`.",
        "tags": [
          "Deposits"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The `walletCharge`, `trackId` or `externalId` of the deposit.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "subAccountId",
            "in": "query",
            "required": false,
            "description": "Required when the deposit was created with `subAccountId`. An id you do not own is refused with 404.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Current state of the deposit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DepositAssetStatusResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid id."
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Deposit not found, or it belongs to another API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/deposit/asset/{externalId}": {
      "get": {
        "operationId": "depositAssetStatus",
        "summary": "Get deposit status and payer",
        "description": "Read a deposit back: whether the PIX was paid, whether the asset was delivered, and who paid the QR code. The `payer` block is only returned to accounts that own a virtual account.",
        "tags": ["Deposits"],
        "parameters": [
          {
            "name": "externalId",
            "in": "path",
            "required": true,
            "description": "The `externalId` of the deposit — your own value, or the UUID returned by the POST.",
            "schema": { "type": "string" }
          },
          {
            "name": "subAccountId",
            "in": "query",
            "required": false,
            "description": "Required when the deposit was created with `subAccountId`. An id you do not own is refused with 404.",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Current state of the deposit.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/DepositAssetStatusResponse" }
              }
            }
          },
          "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "404": { "description": "Deposit not found, or it belongs to another API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/lightning/invoice": {
      "post": {
        "operationId": "createLightningInvoice",
        "summary": "Create a Lightning invoice (Lightning → PIX)",
        "description": "Generate a Lightning invoice that, once paid, triggers an automatic PIX payout.",
        "tags": ["Lightning"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/LightningInvoiceRequest" },
              "examples": {
                "withPixKey": {
                  "summary": "With PIX key",
                  "value": { "value": 1000, "pixKey": "user@email.com", "pixKeyType": "EMAIL" }
                },
                "withQrCode": {
                  "summary": "With PIX BR Code",
                  "value": { "value": 1000, "qrCode": "00020126580014br.gov.bcb.pix..." }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Invoice created.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/LightningInvoiceResponse" }
              }
            }
          },
          "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/webhook/{webhookId}": {
      "post": {
        "operationId": "webhookDelivery",
        "summary": "Webhook delivery (your server receives this)",
        "description": "Hodle POSTs to your endpoint with `event` + `data`. Verify the `X-Hodle-Signature` header (HMAC-SHA256 of `${timestamp}.${rawBody}`).",
        "tags": ["Webhooks"],
        "parameters": [
          { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "X-Hodle-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "HMAC-SHA256 of `${timestamp}.${payload}` using your webhook secret." },
          { "name": "X-Hodle-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } },
          { "name": "X-Hodle-Delivery-Attempt", "in": "header", "required": true, "schema": { "type": "string" }, "description": "`1` on the first delivery, `2` to `4` on retries (10s, 60s and 5min after the previous failed attempt)." }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/WebhookPayload" }
            }
          }
        },
        "responses": {
          "200": { "description": "Acknowledged. 2xx is required to mark delivery as successful." }
        }
      }
    },
    "/api/wallet/create": {
      "post": {
        "tags": [
          "wallet"
        ],
        "summary": "Create a PIN-protected wallet",
        "description": "Requires the six-digit walletPin established on the platform. The PIN is\nverified against an existing protected wallet owned by the target user.\nEach successful call creates fresh wallet keys protected by that same PIN.\nMissing PIN never creates a wallet. Save data.id as walletId and use the\nnew protectedSymmetricKey for reads, transfers and payouts of that wallet.\nThree invalid PIN attempts lock creation for 24 hours.\n`bnb` creates the owner's Safe on BNB Chain (chainId 56); it requires\nthe `BNB_ASSET` feature flag (`403 BNB_FEATURE_DISABLED`) on an approved\naccount (`403 BNB_PLANE_NOT_ACTIVE` while approval is pending or the\naccount is suspended).\nWith `pinScope: WALLET` and a `subAccountId`, the new wallet is wrapped\nunder `walletPin` alone (a random secret of at least 32 characters, e.g.\npasskey-derived; a six-digit PIN only where server-side PIN hardening is\nenabled): the platform PIN is neither required nor able to open it, and\nthree invalid attempts lock only that wallet. EVM networks only. Requires\nthe `WALLET_SCOPED_PIN` feature flag\n(`403 WALLET_SCOPED_PIN_DISABLED`).\n",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "walletPin"
                ],
                "properties": {
                  "walletPin": {
                    "type": "string",
                    "maxLength": 512,
                    "description": "The platform wallet PIN (exactly six digits), verified before creation. With pinScope WALLET, the wallet's own secret (at least 32 random characters, or six digits where PIN hardening is enabled; at most 512), never verified against the platform PIN."
                  },
                  "pinScope": {
                    "type": "string",
                    "enum": [
                      "ACCOUNT",
                      "WALLET"
                    ],
                    "default": "ACCOUNT",
                    "description": "WALLET wraps a sub-account wallet under its own walletPin instead of the platform PIN. Requires subAccountId and an EVM network; not combinable with userId or protectedSymmetricKey."
                  },
                  "protectedSymmetricKey": {
                    "type": "string",
                    "description": "Optional existing owner wallet key used as the PIN reference. The response contains a fresh protected key for the new wallet."
                  },
                  "network": {
                    "type": "string",
                    "enum": [
                      "polygon",
                      "base",
                      "solana"
                    ],
                    "default": "polygon"
                  },
                  "subAccountId": {
                    "type": "string",
                    "description": "Owned customer subaccount containing the new wallet."
                  },
                  "userId": {
                    "type": "string",
                    "description": "Linked target user. Omit when using subAccountId."
                  },
                  "default": {
                    "type": "boolean",
                    "description": "Make this wallet default within its scope. Defaults to true only for the first wallet in that scope."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created a wallet with PIN-protected keys",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "description": "Pass this as walletId in subsequent requests."
                        },
                        "address": {
                          "type": "string"
                        },
                        "network": {
                          "type": "string"
                        },
                        "chainId": {
                          "type": "integer",
                          "description": "EVM chain ID. Omitted for Solana."
                        },
                        "balance": {
                          "type": "number"
                        },
                        "protectedSymmetricKey": {
                          "type": "string",
                          "description": "The new wallet's PIN-protected symmetric key."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request, missing platform PIN, invalid reference key, or unsupported network"
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Incorrect platform wallet PIN"
          },
          "404": {
            "description": "Target user or owned subaccount not found"
          },
          "429": {
            "description": "PIN attempts locked for 24 hours"
          }
        }
      }
    },
    "/api/wallet/get": {
      "post": {
        "operationId": "walletGetPost",
        "summary": "Read a wallet by ID or default network selection",
        "description": "Returns the addresses per network and current balances of the API-key user, or of one subaccount when `subAccountId` is given. `POST /api/wallet/get` serves the same payload with the fields in the body. An explicit walletId scopes the response to that wallet.",
        "tags": [
          "Wallet"
        ],
        "responses": {
          "200": {
            "description": "Wallet.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WalletGetResponse"
                }
              }
            }
          },
          "404": {
            "description": "Wallet not provisioned. With `subAccountId`, an owned sub-account that has no wallet yet answers `404` with `errorCode: SUBACCOUNT_WALLET_NOT_PROVISIONED` (`error`: \"Sub-account has no wallet yet: wallets are created when its KYC is approved\"). Sub-account wallets are created by its KYC approval: wait for `KYC_APPROVED` (or `GET /api/kyc?subAccountId=`) before reading it. An unknown sub-account keeps `Subaccount not found for this platform` without `errorCode`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Sub-account has no wallet yet: wallets are created when its KYC is approved" }, "errorCode": { "type": "string", "enum": ["SUBACCOUNT_WALLET_NOT_PROVISIONED"] } } } } }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "walletId": {
                    "type": "string",
                    "pattern": "^[a-fA-F0-9]{24}$",
                    "description": "ID returned by wallet/create. Scoped by the authenticated owner and subAccountId; no fallback for missing or foreign wallets."
                  },
                  "subAccountId": {
                    "type": "string",
                    "description": "Owned subaccount containing the wallet."
                  },
                  "sync": {
                    "type": "boolean",
                    "default": false
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/card/session/prepare": {
      "post": {
        "operationId": "cardSessionPrepare",
        "summary": "Prepare the card sign-in message",
        "tags": [
          "Card"
        ],
        "description": "Returns the sign-in message the holder wallet EOA signs (EIP-191).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "subAccountId": {
                    "type": "string",
                    "description": "Target a PF sub-account card. Omit for the API-key owner card."
                  },
                  "eoaAddress": {
                    "type": "string",
                    "description": "Only when `requiresSignerAddress` was returned."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Sign-in message.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "walletId": {
                          "type": "string"
                        },
                        "requiresSignerAddress": {
                          "type": "boolean"
                        },
                        "message": {
                          "type": "string",
                          "nullable": true
                        },
                        "eoaAddress": {
                          "type": "string",
                          "nullable": true
                        },
                        "expiresAt": {
                          "type": "string",
                          "nullable": true
                        },
                        "subAccountId": {
                          "type": "string",
                          "nullable": true
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request (`CARD_INVALID_REQUEST`), refused step (`CARD_REQUEST_FAILED`) or sub-account not eligible (`SUBACCOUNT_*`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardError"
                }
              }
            }
          },
          "403": {
            "description": "The production plane lacks the card capability (`CARD_NOT_ENABLED`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardError"
                }
              }
            }
          },
          "404": {
            "description": "Sub-account not owned by this key (`SUBACCOUNT_NOT_FOUND`) or resource not found (`CARD_NOT_FOUND`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardError"
                }
              }
            }
          },
          "409": {
            "description": "No card session (`CARD_SESSION_REQUIRED`): sign in again; or a valid session but the card is not issued yet (`CARD_NOT_ISSUED`, with `stage`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardError"
                }
              }
            }
          },
          "429": {
            "description": "Cooldown running (`CARD_RATE_LIMITED`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardError"
                }
              }
            }
          }
        }
      }
    },
    "/api/card/session": {
      "post": {
        "operationId": "cardSessionCreate",
        "summary": "Open or renew the card session",
        "tags": [
          "Card"
        ],
        "description": "With `walletPin` Hodle unlocks the holder's Hodle wallet (same PIN rules and lockout as payouts: a wrong PIN answers `400` `INVALID_PIN`, three in a row lock the wallet and answer `429` `RATE_LIMITED`) and signs the sign-in itself. With `message` + `signature` it takes a sign-in signed by an external wallet. Calling again renews an expired session.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "title": "Hodle wallet PIN",
                    "type": "object",
                    "required": [
                      "walletPin"
                    ],
                    "properties": {
                      "subAccountId": {
                        "type": "string",
                        "description": "Target a PF sub-account card. Omit for the API-key owner card."
                      },
                      "walletPin": {
                        "type": "string",
                        "description": "The holder wallet secret: the account PIN, or the sub-account wallet's own secret (pinScope WALLET). Never echoed."
                      },
                      "protectedSymmetricKey": {
                        "type": "string",
                        "description": "From POST /api/wallet/keys. Optional: defaults to the card signer wallet's own."
                      },
                      "walletId": {
                        "type": "string",
                        "description": "Optional; must be the holder's card signer wallet."
                      }
                    }
                  },
                  {
                    "title": "External signature",
                    "type": "object",
                    "required": [
                      "message",
                      "signature"
                    ],
                    "properties": {
                      "subAccountId": {
                        "type": "string",
                        "description": "Target a PF sub-account card. Omit for the API-key owner card."
                      },
                      "message": {
                        "type": "string"
                      },
                      "signature": {
                        "type": "string",
                        "pattern": "^0x[0-9a-fA-F]{130}$"
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Session opened.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "subAccountId": {
                          "type": "string",
                          "nullable": true
                        },
                        "sessionExpiresAt": {
                          "type": "string"
                        },
                        "status": {
                          "$ref": "#/components/schemas/CardStatus"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request (`CARD_INVALID_REQUEST`), refused step (`CARD_REQUEST_FAILED`) or sub-account not eligible (`SUBACCOUNT_*`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardError"
                }
              }
            }
          },
          "403": {
            "description": "The production plane lacks the card capability (`CARD_NOT_ENABLED`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardError"
                }
              }
            }
          },
          "404": {
            "description": "Sub-account not owned by this key (`SUBACCOUNT_NOT_FOUND`) or resource not found (`CARD_NOT_FOUND`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardError"
                }
              }
            }
          },
          "409": {
            "description": "No card session (`CARD_SESSION_REQUIRED`): sign in again; or a valid session but the card is not issued yet (`CARD_NOT_ISSUED`, with `stage`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardError"
                }
              }
            }
          },
          "429": {
            "description": "Cooldown running (`CARD_RATE_LIMITED`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardError"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "cardSessionDelete",
        "summary": "Sign out of the card",
        "tags": [
          "Card"
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "subAccountId": {
                    "type": "string",
                    "description": "Target a PF sub-account card. Omit for the API-key owner card."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Session revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "subAccountId": {
                          "type": "string",
                          "nullable": true
                        },
                        "revoked": {
                          "type": "boolean"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request (`CARD_INVALID_REQUEST`), refused step (`CARD_REQUEST_FAILED`) or sub-account not eligible (`SUBACCOUNT_*`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardError"
                }
              }
            }
          },
          "403": {
            "description": "The production plane lacks the card capability (`CARD_NOT_ENABLED`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardError"
                }
              }
            }
          },
          "404": {
            "description": "Sub-account not owned by this key (`SUBACCOUNT_NOT_FOUND`) or resource not found (`CARD_NOT_FOUND`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardError"
                }
              }
            }
          },
          "409": {
            "description": "No card session (`CARD_SESSION_REQUIRED`): sign in again; or a valid session but the card is not issued yet (`CARD_NOT_ISSUED`, with `stage`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardError"
                }
              }
            }
          },
          "429": {
            "description": "Cooldown running (`CARD_RATE_LIMITED`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardError"
                }
              }
            }
          }
        }
      }
    },
    "/api/card": {
      "get": {
        "operationId": "cardGet",
        "summary": "Read the card: stage, KYC, cards and balance",
        "tags": [
          "Card"
        ],
        "parameters": [
          {
            "name": "subAccountId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Target a PF sub-account card. Omit for the API-key owner card."
          }
        ],
        "responses": {
          "200": {
            "description": "Card state.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "data": {
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/CardStatus"
                        },
                        {
                          "type": "object",
                          "properties": {
                            "subAccountId": {
                              "type": "string",
                              "nullable": true
                            },
                            "cards": {
                              "type": "array",
                              "items": {
                                "$ref": "#/components/schemas/Card"
                              }
                            },
                            "balance": {
                              "$ref": "#/components/schemas/CardBalance"
                            }
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request (`CARD_INVALID_REQUEST`), refused step (`CARD_REQUEST_FAILED`) or sub-account not eligible (`SUBACCOUNT_*`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardError"
                }
              }
            }
          },
          "403": {
            "description": "The production plane lacks the card capability (`CARD_NOT_ENABLED`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardError"
                }
              }
            }
          },
          "404": {
            "description": "Sub-account not owned by this key (`SUBACCOUNT_NOT_FOUND`) or resource not found (`CARD_NOT_FOUND`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardError"
                }
              }
            }
          },
          "409": {
            "description": "No card session (`CARD_SESSION_REQUIRED`): sign in again; or a valid session but the card is not issued yet (`CARD_NOT_ISSUED`, with `stage`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardError"
                }
              }
            }
          },
          "429": {
            "description": "Cooldown running (`CARD_RATE_LIMITED`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardError"
                }
              }
            }
          }
        }
      }
    },
    "/api/card/onboarding": {
      "post": {
        "operationId": "cardOnboarding",
        "summary": "Run one onboarding action",
        "tags": [
          "Card"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "action"
                ],
                "properties": {
                  "subAccountId": {
                    "type": "string",
                    "description": "Target a PF sub-account card. Omit for the API-key owner card."
                  },
                  "action": {
                    "$ref": "#/components/schemas/CardOnboardingAction"
                  },
                  "input": {
                    "type": "object",
                    "properties": {
                      "otp": {
                        "type": "string",
                        "description": "`SIGN_UP`: the 6-digit email code the holder received."
                      },
                      "phoneNumber": {
                        "type": "string",
                        "description": "`REQUEST_PHONE_CODE`: E.164."
                      },
                      "phoneCode": {
                        "type": "string",
                        "description": "`VERIFY_PHONE`: the SMS code the holder received."
                      },
                      "sourceOfFunds": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "question": {
                              "type": "string"
                            },
                            "answer": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "New status. `START_KYC` returns `status.kycUrl`.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "subAccountId": {
                          "type": "string",
                          "nullable": true
                        },
                        "action": {
                          "$ref": "#/components/schemas/CardOnboardingAction"
                        },
                        "status": {
                          "$ref": "#/components/schemas/CardStatus"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request (`CARD_INVALID_REQUEST`), refused step (`CARD_REQUEST_FAILED`) or sub-account not eligible (`SUBACCOUNT_*`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardError"
                }
              }
            }
          },
          "403": {
            "description": "The production plane lacks the card capability (`CARD_NOT_ENABLED`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardError"
                }
              }
            }
          },
          "404": {
            "description": "Sub-account not owned by this key (`SUBACCOUNT_NOT_FOUND`) or resource not found (`CARD_NOT_FOUND`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardError"
                }
              }
            }
          },
          "409": {
            "description": "No card session (`CARD_SESSION_REQUIRED`): sign in again; or a valid session but the card is not issued yet (`CARD_NOT_ISSUED`, with `stage`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardError"
                }
              }
            }
          },
          "429": {
            "description": "Cooldown running (`CARD_RATE_LIMITED`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardError"
                }
              }
            }
          }
        }
      }
    },
    "/api/card/fund": {
      "post": {
        "operationId": "cardFundPrepare",
        "summary": "Quote and prepare a card top-up",
        "tags": [
          "Card"
        ],
        "description": "Nothing moves until `submit`. `requestId` is the idempotency key and becomes `fundingId`.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "sourceKey",
                  "amount",
                  "requestId"
                ],
                "properties": {
                  "subAccountId": {
                    "type": "string",
                    "description": "Target a PF sub-account card. Omit for the API-key owner card."
                  },
                  "sourceKey": {
                    "type": "string",
                    "enum": [
                      "USDC_BASE",
                      "USDC_POLYGON",
                      "USDT_POLYGON",
                      "BRLA_POLYGON"
                    ]
                  },
                  "amount": {
                    "type": "string",
                    "example": "20"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Prepared top-up.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/CardFunding"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request (`CARD_INVALID_REQUEST`), refused step (`CARD_REQUEST_FAILED`) or sub-account not eligible (`SUBACCOUNT_*`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardError"
                }
              }
            }
          },
          "403": {
            "description": "The production plane lacks the card capability (`CARD_NOT_ENABLED`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardError"
                }
              }
            }
          },
          "404": {
            "description": "Sub-account not owned by this key (`SUBACCOUNT_NOT_FOUND`) or resource not found (`CARD_NOT_FOUND`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardError"
                }
              }
            }
          },
          "409": {
            "description": "No card session (`CARD_SESSION_REQUIRED`): sign in again; or a valid session but the card is not issued yet (`CARD_NOT_ISSUED`, with `stage`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardError"
                }
              }
            }
          },
          "429": {
            "description": "Cooldown running (`CARD_RATE_LIMITED`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardError"
                }
              }
            }
          }
        }
      }
    },
    "/api/card/fund/{fundingId}/submit": {
      "post": {
        "operationId": "cardFundSubmit",
        "summary": "Submit the signed top-up",
        "tags": [
          "Card"
        ],
        "parameters": [
          {
            "name": "fundingId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "description": "Broadcast at most once; a retry answers the current state.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "title": "Hodle wallet PIN",
                    "type": "object",
                    "required": [
                      "walletPin"
                    ],
                    "properties": {
                      "subAccountId": {
                        "type": "string",
                        "description": "Target a PF sub-account card. Omit for the API-key owner card."
                      },
                      "walletPin": {
                        "type": "string",
                        "description": "The source wallet secret. Hodle signs `signingHash`; same lockout as payouts. Never echoed."
                      },
                      "protectedSymmetricKey": {
                        "type": "string",
                        "description": "Optional; defaults to the source wallet's own."
                      }
                    }
                  },
                  {
                    "title": "External signature",
                    "type": "object",
                    "required": [
                      "signature"
                    ],
                    "properties": {
                      "subAccountId": {
                        "type": "string",
                        "description": "Target a PF sub-account card. Omit for the API-key owner card."
                      },
                      "signature": {
                        "type": "string",
                        "pattern": "^0x0{24}[0-9a-fA-F]{130}$",
                        "description": "12 zero bytes + the 65-byte signature over `signingHash`."
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Submitted top-up.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/CardFunding"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request (`CARD_INVALID_REQUEST`), refused step (`CARD_REQUEST_FAILED`) or sub-account not eligible (`SUBACCOUNT_*`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardError"
                }
              }
            }
          },
          "403": {
            "description": "The production plane lacks the card capability (`CARD_NOT_ENABLED`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardError"
                }
              }
            }
          },
          "404": {
            "description": "Sub-account not owned by this key (`SUBACCOUNT_NOT_FOUND`) or resource not found (`CARD_NOT_FOUND`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardError"
                }
              }
            }
          },
          "409": {
            "description": "No card session (`CARD_SESSION_REQUIRED`): sign in again; or a valid session but the card is not issued yet (`CARD_NOT_ISSUED`, with `stage`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardError"
                }
              }
            }
          },
          "429": {
            "description": "Cooldown running (`CARD_RATE_LIMITED`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardError"
                }
              }
            }
          }
        }
      }
    },
    "/api/card/fund/{fundingId}": {
      "get": {
        "operationId": "cardFundGet",
        "summary": "Track a top-up",
        "tags": [
          "Card"
        ],
        "parameters": [
          {
            "name": "fundingId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "subAccountId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Target a PF sub-account card. Omit for the API-key owner card."
          }
        ],
        "responses": {
          "200": {
            "description": "Top-up.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/CardFunding"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request (`CARD_INVALID_REQUEST`), refused step (`CARD_REQUEST_FAILED`) or sub-account not eligible (`SUBACCOUNT_*`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardError"
                }
              }
            }
          },
          "403": {
            "description": "The production plane lacks the card capability (`CARD_NOT_ENABLED`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardError"
                }
              }
            }
          },
          "404": {
            "description": "Sub-account not owned by this key (`SUBACCOUNT_NOT_FOUND`) or resource not found (`CARD_NOT_FOUND`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardError"
                }
              }
            }
          },
          "409": {
            "description": "No card session (`CARD_SESSION_REQUIRED`): sign in again; or a valid session but the card is not issued yet (`CARD_NOT_ISSUED`, with `stage`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardError"
                }
              }
            }
          },
          "429": {
            "description": "Cooldown running (`CARD_RATE_LIMITED`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardError"
                }
              }
            }
          }
        }
      }
    },
    "/api/card/transactions": {
      "get": {
        "operationId": "cardTransactions",
        "summary": "List card transactions",
        "tags": [
          "Card"
        ],
        "parameters": [
          {
            "name": "subAccountId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Target a PF sub-account card. Omit for the API-key owner card."
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of 20 transactions.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "subAccountId": {
                          "type": "string",
                          "nullable": true
                        },
                        "transactions": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        },
                        "hasNextPage": {
                          "type": "boolean"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request (`CARD_INVALID_REQUEST`), refused step (`CARD_REQUEST_FAILED`) or sub-account not eligible (`SUBACCOUNT_*`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardError"
                }
              }
            }
          },
          "403": {
            "description": "The production plane lacks the card capability (`CARD_NOT_ENABLED`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardError"
                }
              }
            }
          },
          "404": {
            "description": "Sub-account not owned by this key (`SUBACCOUNT_NOT_FOUND`) or resource not found (`CARD_NOT_FOUND`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardError"
                }
              }
            }
          },
          "409": {
            "description": "No card session (`CARD_SESSION_REQUIRED`): sign in again; or a valid session but the card is not issued yet (`CARD_NOT_ISSUED`, with `stage`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardError"
                }
              }
            }
          },
          "429": {
            "description": "Cooldown running (`CARD_RATE_LIMITED`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardError"
                }
              }
            }
          }
        }
      }
    },
    "/api/card/freeze": {
      "post": {
        "operationId": "cardFreeze",
        "summary": "Freeze or unfreeze a card",
        "tags": [
          "Card"
        ],
        "description": "Unfreezing needs a card session signed in the last 5 minutes.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "cardId",
                  "frozen",
                  "requestId"
                ],
                "properties": {
                  "subAccountId": {
                    "type": "string",
                    "description": "Target a PF sub-account card. Omit for the API-key owner card."
                  },
                  "cardId": {
                    "type": "string"
                  },
                  "frozen": {
                    "type": "boolean"
                  },
                  "requestId": {
                    "type": "string",
                    "pattern": "^[a-zA-Z0-9-]{16,80}$"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "New frozen state.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "subAccountId": {
                          "type": "string",
                          "nullable": true
                        },
                        "cardId": {
                          "type": "string"
                        },
                        "frozen": {
                          "type": "boolean"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request (`CARD_INVALID_REQUEST`), refused step (`CARD_REQUEST_FAILED`) or sub-account not eligible (`SUBACCOUNT_*`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardError"
                }
              }
            }
          },
          "403": {
            "description": "The production plane lacks the card capability (`CARD_NOT_ENABLED`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardError"
                }
              }
            }
          },
          "404": {
            "description": "Sub-account not owned by this key (`SUBACCOUNT_NOT_FOUND`) or resource not found (`CARD_NOT_FOUND`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardError"
                }
              }
            }
          },
          "409": {
            "description": "No card session (`CARD_SESSION_REQUIRED`): sign in again; or a valid session but the card is not issued yet (`CARD_NOT_ISSUED`, with `stage`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardError"
                }
              }
            }
          },
          "429": {
            "description": "Cooldown running (`CARD_RATE_LIMITED`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardError"
                }
              }
            }
          }
        }
      }
    }
  },
  "tags": [
    { "name": "Subaccounts", "description": "Create and read end-user subaccounts." },
    { "name": "KYC", "description": "Submit and inspect KYC for end-users." },
    { "name": "Account", "description": "Statement and balances." },
    { "name": "Pricing", "description": "Indicative quotes for BRL ↔ asset pairs." },
    { "name": "Wallet", "description": "Read wallets, fetch keys, transfer USDT, run PIX payouts." },
    { "name": "Deposits", "description": "PIX → crypto on-ramp." },
    { "name": "Lightning", "description": "Lightning ↔ PIX off-ramp." },
    { "name": "Webhooks", "description": "Realtime event delivery." },
    {"name": "Card", "description": "Virtual card: sign-in, onboarding, top-ups and management."}
  ]
}
