Squads

Create a Squad shared account

Create a Squad (RFC-018) and its Config UTxO at the SquadValidator.

Thin wrapper: payload validation → idempotency cache → ``SquadAdapter.create_instance`` → response caching. The creator becomes the sole OWNER member; the squad account row is persisted with ``vk=null`` (the squad has no key — chain enforces all authority). Caller-identity (ACTOR_MISMATCH) is enforced at the API Gateway, not here. Errors follow ``adding-api-endpoints.md``. Optional ``invitee_account_ids`` creates + invites atomically (every invitee validated before the irreversible tx). Optional ``metadata`` (description, emoji, image_url, location) is off-chain display data only. Errors: 400: INVALID_NAME, INVALID_DESCRIPTION, INVALID_EMOJI, INVALID_IMAGE_URL, INVALID_LOCATION, CANNOT_INVITE_SELF 404: ACCOUNT_NOT_FOUND 409: IDEMPOTENCY_KEY_REUSED 422: INVALID_CREATOR_TYPE, SQUAD_AS_SQUAD_MEMBER_FORBIDDEN, ALREADY_A_MEMBER 503: HYDRA_UNAVAILABLE

Parâmetros

Corpo da requisição

SquadCreateRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Owner: edit a squad's display metadata (name / emoji / image / location)

Edit a squad's off-chain display fields (RFC-018). OWNER-only. **No Cardano tx** — a conditional update of the squad's display-metadata projection (name lives off-chain, not in the Config datum). Partial update: omitted fields are left unchanged; an explicit ``null`` clears an optional metadata field (``name`` is required and not clearable). Allowed on OPEN and CLOSED squads alike (purely cosmetic). Caller-identity (ACTOR_MISMATCH) is enforced at the API Gateway, not here. Errors: 400: INVALID_NAME, INVALID_DESCRIPTION, INVALID_EMOJI, INVALID_IMAGE_URL, INVALID_LOCATION 403: INSUFFICIENT_ROLE, NOT_A_SQUAD_MEMBER 404: SQUAD_NOT_FOUND, ACCOUNT_NOT_FOUND 409: IDEMPOTENCY_KEY_REUSED

Parâmetros

Corpo da requisição

SquadUpdateRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Member: grant / refresh auto-collect consent for a conta

Grant (or refresh) a standing, capped consent to auto-settle the caller's own share of ``rex_id`` each cycle (B-SQ-04 Assinatura). Own-share-only; off-chain (a projection write). ``max_amount`` caps per-cycle collection — a posted share above it SUSPENDS the consent (``consent_state=REQUIRES_RECONSENT``) rather than over-collecting. A re-grant re-activates a suspended consent. Errors: 400: INVALID_AMOUNT, UNSUPPORTED_CURRENCY 403: INSUFFICIENT_ROLE, NOT_A_SQUAD_MEMBER 404: SQUAD_NOT_FOUND, ACCOUNT_NOT_FOUND, REX_NOT_FOUND 409: IDEMPOTENCY_KEY_REUSED 422: SQUAD_CLOSED, SQUAD_FROZEN

Parâmetros

Corpo da requisição

ConsentRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Member: revoke auto-collect consent (one tap)

Revoke an auto-collect consent (B-SQ-04). Hard-deletes the consent row so future cycles no longer auto-collect this member's share. Always allowed (even when frozen / closed). The caller may only revoke their own consent. Errors: 404: SQUAD_NOT_FOUND, ACCOUNT_NOT_FOUND, CONSENT_NOT_FOUND 409: IDEMPOTENCY_KEY_REUSED

Parâmetros

Corpo da requisição

ConsentRevokeRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Close the squad (OWNER; terminal, irreversible)

Close the squad (RFC-018 §5.1, SQ-14). An OWNER closes once every member is at net-zero: the tx consumes the OPEN Config UTxO and recreates it with ``state="CLOSED"``. After close every write referencing the Config fails the validator's ``configIsOpen`` check (SI-7); reads continue indefinitely. Close is irreversible — there is no ``/reopen``. The net-zero preconditions (FUNDS_REMAINING / OPEN_ACCOUNTING_ROWS) are off-chain fast-fails and carry a ``details.non_zero_positions`` breakdown. Errors: 403: NOT_A_SQUAD_MEMBER, INSUFFICIENT_ROLE 404: SQUAD_NOT_FOUND, ACCOUNT_NOT_FOUND 409: IDEMPOTENCY_KEY_REUSED 422: SQUAD_ALREADY_CLOSED, FUNDS_REMAINING, OPEN_ACCOUNTING_ROWS, SETTLEMENT_IN_PROGRESS 503: HYDRA_UNAVAILABLE

Parâmetros

Corpo da requisição

CloseRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Contribute to a Squad (kind=FUNDED deposits QBRL; kind=ACCOUNTING records a split)

Record a squad contribution (RFC-018 §5.1, SQ-11 / SQ-13).

``kind=FUNDED`` moves QBRL from the actor's BancoBRL custody to a Balance UTxO at the SquadValidator (Config read as a reference input) and records an obligation. ``kind=ACCOUNTING`` records a non-monetary split: it resolves the split into per-debtor **share** UTxOs and mints the vQBRL across them (no QBRL moves). Caller-identity (ACTOR_MISMATCH) is enforced at the API Gateway. Errors: 400: UNSUPPORTED_CURRENCY, INVALID_AMOUNT, INVALID_KIND, INVALID_SPLIT, AMOUNTS_DO_NOT_SUM, UNKNOWN_MEMBER_IN_SPLIT, INVALID_DESCRIPTION, INVALID_SOURCE_TX 403: NOT_A_SQUAD_MEMBER, INSUFFICIENT_ROLE 404: SQUAD_NOT_FOUND, ACCOUNT_NOT_FOUND 409: IDEMPOTENCY_KEY_REUSED 422: INSUFFICIENT_BALANCE, SQUAD_CLOSED 503: HYDRA_UNAVAILABLE

Parâmetros

Corpo da requisição

ContributionRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Void (forgive) an accounting entry's unsettled shares (creditor only)

Void an accounting entry's still-unsettled shares (RFC-018 §5.1, SQ-13).

Implemented via ``VoidShare``: the **creditor** (original actor) consumes and burns the entry's remaining share UTxOs (no QBRL moves). Already-settled shares are simply already-consumed UTxOs, so voiding operates on whatever remains. Caller-identity is enforced at the API Gateway. Errors: 403: NOT_THE_CREDITOR, NOT_A_SQUAD_MEMBER, INSUFFICIENT_ROLE 404: SQUAD_NOT_FOUND, ACCOUNT_NOT_FOUND, ACCOUNTING_NOT_FOUND 409: IDEMPOTENCY_KEY_REUSED 422: SQUAD_CLOSED 503: HYDRA_UNAVAILABLE

Parâmetros

Corpo da requisição

VoidContributionRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Owner: manually re-split one expense's open shares

OWNER escape hatch (RFC-018): manually re-divide one expense's still-open shares when the general rule can't (e.g. a partially-settled entry). The entry is then flagged so automatic re-splits leave it alone. Errors: 400: INVALID_SPLIT, AMOUNTS_DO_NOT_SUM, UNKNOWN_MEMBER_IN_SPLIT 403: INSUFFICIENT_ROLE, NOT_A_SQUAD_MEMBER 404: SQUAD_NOT_FOUND, ACCOUNT_NOT_FOUND, ACCOUNTING_NOT_FOUND 409: IDEMPOTENCY_KEY_REUSED 422: SQUAD_CLOSED 503: HYDRA_UNAVAILABLE

Parâmetros

Corpo da requisição

EntrySplitOverrideRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Owner: freeze a squad (wind-down; reversible)

Freeze a squad for wind-down (RFC-018). OWNER-only. **No Cardano tx** — flips an off-chain ``frozen`` flag on the squad's META row. The squad stays ``state=OPEN`` and fully readable, but deposits/spends/accounting and all roster changes are then rejected (422 SQUAD_FROZEN); settlement, close, decline-invite, and metadata edits keep working. Freezing is a prerequisite for ``simplify-debts``. Idempotent: freezing an already-frozen squad is a 200 no-op with ``changed=false``. Errors: 403: NOT_A_SQUAD_MEMBER, INSUFFICIENT_ROLE 404: SQUAD_NOT_FOUND, ACCOUNT_NOT_FOUND 409: IDEMPOTENCY_KEY_REUSED 422: SQUAD_CLOSED

Parâmetros

Corpo da requisição

SquadFreezeRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Owner: remove a squad's savings goal

Remove a squad's savings goal (B-SQ-05). OWNER-only, off-chain. Allowed on OPEN and CLOSED squads alike (cleanup). Idempotent: clearing an absent goal still returns ``goal: null``. Only ``actor_account_id`` is read from the body. Errors: 403: INSUFFICIENT_ROLE, NOT_A_SQUAD_MEMBER 404: SQUAD_NOT_FOUND, ACCOUNT_NOT_FOUND 409: IDEMPOTENCY_KEY_REUSED

Parâmetros

Corpo da requisição

SquadGoalDeleteRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Owner: set or edit a squad's savings goal (target amount + optional date)

Set or edit a squad's savings goal (B-SQ-05). OWNER-only, **off-chain** (a projection write — no Cardano tx). The goal constrains nothing; it only measures. ``funded_cents`` / ``progress`` are computed from the live pool balance, and ``achieved_at`` is stamped (sticky) the first moment the pool reaches the target. Errors: 400: INVALID_GOAL_AMOUNT, INVALID_GOAL_DATE 403: INSUFFICIENT_ROLE, NOT_A_SQUAD_MEMBER 404: SQUAD_NOT_FOUND, ACCOUNT_NOT_FOUND 409: IDEMPOTENCY_KEY_REUSED 422: SQUAD_CLOSED

Parâmetros

Corpo da requisição

SquadGoalRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Invite one or more accounts to a Squad

Invite one or more accounts (RFC-018 invite flow). OWNER-only. Writes a PENDING invite projection row per invitee — **no Cardano tx**; an invitee enters the on-chain roster only when they accept. **Partial-success**: the 201 body reports each invitee as ``invited``/``skipped``/``failed`` (see ``SquadBatchInviteResponse``); per-invitee problems (self, already a member/invited, not found, is a squad, duplicated) do not fail the call. Only the structural checks below hard-fail. Caller-identity (ACTOR_MISMATCH) is enforced at the API Gateway, not here. Errors: 403: INSUFFICIENT_ROLE, NOT_A_SQUAD_MEMBER 404: SQUAD_NOT_FOUND 409: IDEMPOTENCY_KEY_REUSED 422: SQUAD_CLOSED

Parâmetros

Corpo da requisição

InviteCreateRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Revoke a pending Squad invitation

Revoke a pending invite (RFC-018 invite flow). OWNER-only; projection-only state flip, no tx. Caller-identity is enforced at the API Gateway. Errors: 403: INSUFFICIENT_ROLE, NOT_A_SQUAD_MEMBER 404: SQUAD_NOT_FOUND, ACCOUNT_NOT_FOUND, INVITE_NOT_FOUND 409: IDEMPOTENCY_KEY_REUSED 422: SQUAD_CLOSED

Parâmetros

Corpo da requisição

RevokeInviteRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Accept a Squad invitation

Accept a pending invite (RFC-018 invite flow). The invitee enters the on-chain roster as a SPENDER via ``build_change_membership_tx``, custodially authored by a current OWNER (ChangeMembership is OWNER-gated). Caller-identity is enforced at the API Gateway. Errors: 404: SQUAD_NOT_FOUND, ACCOUNT_NOT_FOUND, INVITE_NOT_FOUND 409: IDEMPOTENCY_KEY_REUSED 422: SQUAD_CLOSED, ALREADY_A_MEMBER, NO_CURRENT_OWNER 503: HYDRA_UNAVAILABLE

Parâmetros

Corpo da requisição

InviteAcceptRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Decline a Squad invitation

Decline a pending invite (RFC-018 invite flow). Projection-only state flip; no tx. Intentionally NOT OPEN-gated, so an invitee can tidy a stale invite. Errors: 404: SQUAD_NOT_FOUND, ACCOUNT_NOT_FOUND, INVITE_NOT_FOUND 409: IDEMPOTENCY_KEY_REUSED

Parâmetros

Corpo da requisição

InviteDeclineRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Remove a member from a Squad

Remove a member (RFC-018 §5.1, SQ-10). Consumes the Config UTxO and recreates it with the member dropped from the ``members`` map (validator enforces "≥1 OWNER remains"). The leaver's **open accounting debts are redistributed** proportionally across the entry's remaining members first (no write-offs; settled members inherit a top-up) — see ``debt_resolution`` on the response. Pooled funds still block (``MEMBER_HAS_OUTSTANDING_BALANCE``); being **owed** money on an open share still blocks (``MEMBER_HAS_OUTSTANDING_ACCOUNTING`` — creditor side only). Caller-identity (ACTOR_MISMATCH) is enforced at the API Gateway, not here. Errors: 403: INSUFFICIENT_ROLE, NOT_A_SQUAD_MEMBER 404: SQUAD_NOT_FOUND, ACCOUNT_NOT_FOUND, MEMBER_NOT_FOUND 409: IDEMPOTENCY_KEY_REUSED 422: SQUAD_CLOSED, LAST_OWNER_CANNOT_BE_REMOVED, MEMBER_HAS_OUTSTANDING_BALANCE, MEMBER_HAS_OUTSTANDING_ACCOUNTING 503: HYDRA_UNAVAILABLE

Parâmetros

Corpo da requisição

RemoveMemberRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Change a member's quota (cota) count

Change how many people a member represents (RFC-018 quotas). A member may edit their own quota; an OWNER may edit anyone's. Re-divides every still-open EQUAL expense at the new quota. **Locked once any entry is settled/voided.** Errors: 400: INVALID_QUOTA 403: INSUFFICIENT_ROLE, NOT_A_SQUAD_MEMBER 404: SQUAD_NOT_FOUND, ACCOUNT_NOT_FOUND, MEMBER_NOT_FOUND 409: IDEMPOTENCY_KEY_REUSED, QUOTA_CHANGE_LOCKED 422: SQUAD_CLOSED 503: HYDRA_UNAVAILABLE

Parâmetros

Corpo da requisição

UpdateMemberQuotaRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Promote/demote a member between OWNER and SPENDER

Change a member's role (RFC-018). OWNER-only, and an owner may only change **other** members' roles (never their own), so self-promotion is impossible. The role lives in the on-chain Config datum, so this rewrites it via ``ChangeMembership`` (no new redeemer); a request matching the member's current role is a no-op (no tx, ``changed: false``). Caller-identity is enforced at the API Gateway. Errors: 400: INVALID_ROLE 403: INSUFFICIENT_ROLE, NOT_A_SQUAD_MEMBER 404: SQUAD_NOT_FOUND, ACCOUNT_NOT_FOUND, MEMBER_NOT_FOUND 409: IDEMPOTENCY_KEY_REUSED 422: SQUAD_CLOSED, CANNOT_CHANGE_OWN_ROLE, LAST_OWNER_CANNOT_BE_DEMOTED 503: HYDRA_UNAVAILABLE

Parâmetros

Corpo da requisição

ChangeMemberRoleRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Owner: enable / edit / disable a squad's monthly cycles

Enable, edit, or disable monthly cycles for a squad (B-SQ-04). OWNER-only, **off-chain** (a projection write — no Cardano tx). ``billing_day`` (1–28) is the dia de fechamento; ``null`` disables. Billing fires at 00:00 in ``timezone``. Errors: 400: INVALID_BILLING_DAY, INVALID_TIMEZONE 403: INSUFFICIENT_ROLE, NOT_A_SQUAD_MEMBER 404: SQUAD_NOT_FOUND, ACCOUNT_NOT_FOUND 409: IDEMPOTENCY_KEY_REUSED 422: SQUAD_CLOSED, SQUAD_FROZEN

Parâmetros

Corpo da requisição

RecurrenceRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Owner: create a recurring expense (conta / bill template)

Create a conta that auto-posts each cycle (B-SQ-04). OWNER-only, off-chain. A fixed conta posts at ``amount``; a ``variable`` one posts a placeholder awaiting the payer's ``/confirm``. ``split`` is the same sealed split as a contribution. Errors: 400: INVALID_AMOUNT, INVALID_DESCRIPTION, INVALID_SPLIT, AMOUNTS_DO_NOT_SUM, UNKNOWN_MEMBER_IN_SPLIT, UNSUPPORTED_CURRENCY 403: INSUFFICIENT_ROLE, NOT_A_SQUAD_MEMBER 404: SQUAD_NOT_FOUND, ACCOUNT_NOT_FOUND 409: IDEMPOTENCY_KEY_REUSED 422: SQUAD_CLOSED, SQUAD_FROZEN

Parâmetros

Corpo da requisição

RecurringExpenseRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Owner: delete a recurring expense (conta)

Delete a conta (B-SQ-04). OWNER-only, off-chain. Stops future postings; already-posted expenses are ordinary entries and stay. Errors: 403: INSUFFICIENT_ROLE, NOT_A_SQUAD_MEMBER 404: SQUAD_NOT_FOUND, REX_NOT_FOUND 409: IDEMPOTENCY_KEY_REUSED 422: SQUAD_CLOSED

Parâmetros

Corpo da requisição

RecurringExpenseDeleteRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Owner: edit a recurring expense (conta)

Edit a conta (B-SQ-04). OWNER-only, off-chain. Partial update; future cycle posts use the new values, already-posted expenses are unaffected. Errors mirror create, plus 404 REX_NOT_FOUND.

Parâmetros

Corpo da requisição

RecurringExpensePatchRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Payer: confirm a variable conta's real amount for the current period

Confirm a variable conta's real amount (B-SQ-04). Payer-only. Turns the current period's PENDING_CONFIRMATION placeholder into a live on-chain ACCOUNTING expense (minting per-debtor shares). Errors: 400: INVALID_AMOUNT, UNSUPPORTED_CURRENCY 403: NOT_THE_PAYER 404: SQUAD_NOT_FOUND, REX_NOT_FOUND, PENDING_CONFIRMATION_NOT_FOUND 409: IDEMPOTENCY_KEY_REUSED 422: SQUAD_CLOSED, SQUAD_FROZEN, ALREADY_CONFIRMED 503: HYDRA_UNAVAILABLE

Parâmetros

Corpo da requisição

ConfirmVariableRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Owner: remove a squad's spend-approval policy

Remove a squad's spend-approval policy (B-SQ-06). OWNER-only, off-chain. Allowed on OPEN and CLOSED alike (cleanup). Pending spend-requests are unaffected — each carries the policy snapshot it was created under. Idempotent: clearing an absent policy returns ``rules: null``. Errors: 403: INSUFFICIENT_ROLE, NOT_A_SQUAD_MEMBER 404: SQUAD_NOT_FOUND, ACCOUNT_NOT_FOUND 409: IDEMPOTENCY_KEY_REUSED

Parâmetros

Corpo da requisição

SquadRulesDeleteRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Owner: set or edit a squad's spend-approval policy (Regras)

Set or edit a squad's spend-approval policy (B-SQ-06). OWNER-only, **off-chain** (a projection write — no Cardano tx). A spend *above* ``threshold_amount`` then requires ``approvals_required`` distinct approvers (from ``approvers`` = OWNERS | ALL_MEMBERS) before it executes. Errors: 400: INVALID_THRESHOLD, INVALID_APPROVALS_REQUIRED, INVALID_APPROVERS 403: INSUFFICIENT_ROLE, NOT_A_SQUAD_MEMBER 404: SQUAD_NOT_FOUND, ACCOUNT_NOT_FOUND 409: IDEMPOTENCY_KEY_REUSED 422: SQUAD_CLOSED, SQUAD_FROZEN

Parâmetros

Corpo da requisição

SquadRulesRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Settle the caller's own shares (per-debtor self-settle)

Per-debtor self-settle (RFC-018 §5.3, SQ-13). The caller discharges the shares where THEY are the debtor: one tx pays each creditor ``share_cents`` QBRL and burns the share vQBRL via ``SettleShare``. The settle is funded from the caller's **squad deposits first** — those are drained back to their personal custody in a prior ``Spend`` tx (``squad_funds_withdrawn_cents`` / ``withdrawal_tx_id`` report it), any excess staying liquid in custody — then any shortfall comes from their existing custody. ``entry_seq`` optionally narrows to one expense. A caller who owes nothing but has a squad deposit gets **201** with ``settled_shares: 0`` and the withdrawal fields (the deposit is returned to their personal custody; ``tx_id == withdrawal_tx_id``) — ``ACCOUNTING_NOT_FOUND`` is now returned only when the caller owed nothing AND had no deposit. Caller-identity is enforced at the API Gateway. Errors: 404: SQUAD_NOT_FOUND, ACCOUNT_NOT_FOUND, ACCOUNTING_NOT_FOUND 409: IDEMPOTENCY_KEY_REUSED 422: SQUAD_CLOSED, INSUFFICIENT_BALANCE 503: HYDRA_UNAVAILABLE

Parâmetros

Corpo da requisição

SettleRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Simplify the squad's debts (OWNER; minimal multi-party netting)

Collapse the open accounting-share graph into the minimal set of net debts (RFC-018 netting). An OWNER triggers it; the handler computes the Splitwise-style minimum-cash-flow plan and rewrites the chain to match — reissuing the minimal net shares on fresh entries, then voiding all originals (which are kept as frozen history). Total open debt is conserved (``vqbrl_minted == vqbrl_burned``); only the number of debts shrinks. ``no_op: true`` when the graph is already minimal (no on-chain work). The op is a resumable multi-tx sequence — a retry with the same Idempotency-Key continues a partial run rather than restarting. Errors: 403: NOT_A_SQUAD_MEMBER, INSUFFICIENT_ROLE 404: SQUAD_NOT_FOUND, ACCOUNT_NOT_FOUND 409: IDEMPOTENCY_KEY_REUSED, SIMPLIFY_IN_PROGRESS 422: SQUAD_CLOSED, CREDITOR_UNRESOLVABLE, SQUAD_TOO_LARGE_TO_SIMPLIFY 503: HYDRA_UNAVAILABLE

Parâmetros

Corpo da requisição

SquadSimplifyRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Approve a pending squad spend-request (the Nth approval executes it)

Record one approval on a PENDING_APPROVAL spend-request (B-SQ-06).

An eligible approver (distinct from the requester and prior approvers) approves. Before the Nth approval → **200** with the updated approvals list. On the Nth → the spend executes atomically and this returns **201** with the executed spend result (tx_id, …). Insufficient pool at execution → the request flips FAILED and 422 INSUFFICIENT_BALANCE is returned (no partial movement). Errors: 403: NOT_AN_APPROVER, NOT_A_SQUAD_MEMBER, CANNOT_APPROVE_OWN_REQUEST, INSUFFICIENT_ROLE 404: SPEND_REQUEST_NOT_FOUND, SQUAD_NOT_FOUND, ACCOUNT_NOT_FOUND 409: ALREADY_APPROVED, IDEMPOTENCY_KEY_REUSED 422: APPROVAL_NOT_PENDING, INSUFFICIENT_BALANCE, SQUAD_FROZEN, SQUAD_CLOSED 503: HYDRA_UNAVAILABLE

Parâmetros

Corpo da requisição

SpendRequestApproveRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Reject (kill) a pending squad spend-request

A single eligible approver rejects a PENDING_APPROVAL spend-request (B-SQ-06). Sticky: a rejected request is terminal (a later approve → 422 APPROVAL_NOT_PENDING). Errors: 403: NOT_AN_APPROVER, NOT_A_SQUAD_MEMBER, INSUFFICIENT_ROLE 404: SPEND_REQUEST_NOT_FOUND, SQUAD_NOT_FOUND, ACCOUNT_NOT_FOUND 409: IDEMPOTENCY_KEY_REUSED 422: APPROVAL_NOT_PENDING, SQUAD_FROZEN, SQUAD_CLOSED

Parâmetros

Corpo da requisição

SpendRequestRejectRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Spend from a Squad to an external recipient

Spend QBRL out of a squad (RFC-018 §5.1, SQ-12, B-SQ-07).

Exactly one destination. **Internal** (``recipient_account_id``): a SPENDER/OWNER moves QBRL to that account's BancoBRL custody; the SquadValidator ``Spend`` redeemer enforces role/witness/value-conservation on-chain; returns **201** ``state:"OPEN"``. **External Pix** (``pix_destination``, B-SQ-07): the pool's QBRL bridges to the GL clearing account and the deferred Pix rail sends it out; the DICT key is resolved pre-debit (recipient name in the ``payout`` block), and it returns **201** ``state:"PROCESSING"`` with ``payout:{ rail, end_to_end_id, recipient_name, status }`` — the terminal SPEND_SETTLED / SPEND_FAILED (pool auto-refunded) surface in the feed. Caller-identity (ACTOR_MISMATCH) is enforced at the API Gateway, not here.

B-SQ-06 (Regras): if the squad has a ``spend_rules`` policy and the amount is *above* the threshold, no money moves — the spend (internal or Pix) is parked as a PENDING_APPROVAL request and this returns **202** with ``{spend_request_id, state:"PENDING_APPROVAL", …}``. Otherwise it executes and returns **201**. Errors: 400: UNSUPPORTED_CURRENCY, INVALID_AMOUNT, CANNOT_SPEND_TO_SELF, MISSING_DESTINATION, AMBIGUOUS_DESTINATION, INVALID_PIX_KEY 403: NOT_A_SQUAD_MEMBER, INSUFFICIENT_ROLE 404: SQUAD_NOT_FOUND, RECIPIENT_NOT_FOUND, ACCOUNT_NOT_FOUND, PIX_KEY_NOT_FOUND 409: IDEMPOTENCY_KEY_REUSED 422: INSUFFICIENT_BALANCE, SQUAD_CLOSED, SQUAD_FROZEN, PIX_RAIL_UNAVAILABLE 503: HYDRA_UNAVAILABLE

Parâmetros

Corpo da requisição

SpendRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Owner: unfreeze a squad (resume normal activity)

Unfreeze a squad (RFC-018), re-allowing deposits/spends/accounting and roster changes. OWNER-only. **No Cardano tx.** Does NOT clear the sticky ``simplified`` marker. Idempotent: unfreezing an already-open squad is a 200 no-op with ``changed=false``. Errors: 403: NOT_A_SQUAD_MEMBER, INSUFFICIENT_ROLE 404: SQUAD_NOT_FOUND, ACCOUNT_NOT_FOUND 409: IDEMPOTENCY_KEY_REUSED 422: SQUAD_CLOSED

Parâmetros

Corpo da requisição

SquadFreezeRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas