Squads
10 operações em Quadra Core API 0.5.0.
/v1/accounts/{acc_id}/invitationsList the squad invitations addressed to an account (the inbox)
The path account's PENDING squad invitations via the GSI8 invitee index (RFC-018 invite flow). Account-scoped (gateway enforces caller == acc_id), like ``GET /v1/accounts/{acc_id}/squads``. Errors: 404 ACCOUNT_NOT_FOUND.
Parâmetros
| Nome | Tipo | Detalhe |
|---|---|---|
| acc_id | string | pathobrigatório |
Respostas
| Status | Corpo | Detalhe |
|---|---|---|
| 200 | AccountInvitationListResponse | Resposta bem-sucedida |
| 422 | HTTPValidationError | Erro de validação |
/v1/accounts/{acc_id}/squadsList the squads an account is a member of
The caller's (path account's) squads via GSI8, joined with CONFIG and the caller's net position (RFC-018, SQ-18). Errors: 404 ACCOUNT_NOT_FOUND.
Parâmetros
| Nome | Tipo | Detalhe |
|---|---|---|
| acc_id | string | pathobrigatório |
| state | string, opcional | query |
| limit | integer | query |
| cursor | string, opcional | query |
Respostas
| Status | Corpo | Detalhe |
|---|---|---|
| 200 | AccountSquadListResponse | Resposta bem-sucedida |
| 422 | HTTPValidationError | Erro de validação |
/v1/accounts/{acc_id}/squads/{sqd_id}/settlement-planGet the caller's open debts in a squad (settlement plan)
The caller's open debts in a squad and how to settle them (RFC-018, SQ-16).
The caller is the path account (``acc_id``). Returns the shares where they are the debtor (each with its ``share_utxo_ref``), their open claims (informational), and an ``execution_endpoint`` whose ``body_template`` is POST-able verbatim to ``/v1/squads/{sqd_id}/settle`` (SQ-17). Errors: 403: NOT_A_SQUAD_MEMBER 404: ACCOUNT_NOT_FOUND, SQUAD_NOT_FOUND 422: SQUAD_CLOSED
Parâmetros
| Nome | Tipo | Detalhe |
|---|---|---|
| acc_id | string | pathobrigatório |
| sqd_id | string | pathobrigatório |
Respostas
| Status | Corpo | Detalhe |
|---|---|---|
| 200 | SettlementPlanResponse | Resposta bem-sucedida |
| 422 | HTTPValidationError | Erro de validação |
/v1/squadsList all squads (admin)
Global squad listing via GSI9 (RFC-018, SQ-18), scoped to the calling tenant.
Admin-only — locked down at the API gateway; the bank app uses ``GET /v1/accounts/{me}/squads`` instead. **Page until `next_cursor` is null** — a short page is not the end of the list.
Parâmetros
| Nome | Tipo | Detalhe |
|---|---|---|
| state | string, opcional | query |
| limit | integer | query |
| cursor | string, opcional | query |
Respostas
| Status | Corpo | Detalhe |
|---|---|---|
| 200 | SquadListResponse | Resposta bem-sucedida |
| 422 | HTTPValidationError | Erro de validação |
/v1/squads/{sqd_id}Get squad detail (config + members + ledger summary)
Squad detail (RFC-018, SQ-18). Errors: 403 NOT_A_SQUAD_MEMBER, 404 ACCOUNT_NOT_FOUND / SQUAD_NOT_FOUND. CLOSED squads are returned indefinitely.
Parâmetros
| Nome | Tipo | Detalhe |
|---|---|---|
| sqd_id | string | pathobrigatório |
| caller_account_id | string | queryobrigatório The calling account; must be a member |
Respostas
| Status | Corpo | Detalhe |
|---|---|---|
| 200 | SquadDetailResponse | Resposta bem-sucedida |
| 422 | HTTPValidationError | Erro de validação |
/v1/squads/{sqd_id}/invitationsList a squad's pending invitations
A squad's PENDING invitations (RFC-018 invite flow). Member-scoped. Errors: 403 NOT_A_SQUAD_MEMBER, 404 ACCOUNT_NOT_FOUND / SQUAD_NOT_FOUND.
Parâmetros
| Nome | Tipo | Detalhe |
|---|---|---|
| sqd_id | string | pathobrigatório |
| caller_account_id | string | queryobrigatório The calling account; must be a member |
Respostas
| Status | Corpo | Detalhe |
|---|---|---|
| 200 | SquadInvitationListResponse | Resposta bem-sucedida |
| 422 | HTTPValidationError | Erro de validação |
/v1/squads/{sqd_id}/membersGet a squad's active member roster
Active member roster (RFC-018, SQ-18). Errors: 403 NOT_A_SQUAD_MEMBER, 404 ACCOUNT_NOT_FOUND / SQUAD_NOT_FOUND.
Parâmetros
| Nome | Tipo | Detalhe |
|---|---|---|
| sqd_id | string | pathobrigatório |
| caller_account_id | string | queryobrigatório The calling account; must be a member |
Respostas
| Status | Corpo | Detalhe |
|---|---|---|
| 200 | SquadMemberListResponse | Resposta bem-sucedida |
| 422 | HTTPValidationError | Erro de validação |
/v1/squads/{sqd_id}/simplify-previewPreview debt simplification (before vs after net debts; OWNER-only)
Dry-run of ``POST /v1/squads/{sqd_id}/simplify-debts`` (RFC-018 netting). Returns the current gross open-debt edges and the minimal net set a simplification would produce, so the app can show "before vs after" without executing. OWNER-only (only an OWNER can execute the simplification). Errors: 403 NOT_A_SQUAD_MEMBER / INSUFFICIENT_ROLE, 404 ACCOUNT_NOT_FOUND/SQUAD_NOT_FOUND, 422 SQUAD_CLOSED.
Parâmetros
| Nome | Tipo | Detalhe |
|---|---|---|
| sqd_id | string | pathobrigatório |
| caller_account_id | string | queryobrigatório The calling account; must be the OWNER |
Respostas
| Status | Corpo | Detalhe |
|---|---|---|
| 200 | SquadSimplifyPreviewResponse | Resposta bem-sucedida |
| 422 | HTTPValidationError | Erro de validação |
/v1/squads/{sqd_id}/spend-requestsList a squad's N-of-M spend-requests with approval history (Regras)
The transparency list of spend-requests awaiting or resolved through N-of-M approval (B-SQ-06), with full approval history. Every member can read it. ``?state=`` filters by effective state (lazy expiry applied). Errors: 403 NOT_A_SQUAD_MEMBER, 404 ACCOUNT_NOT_FOUND / SQUAD_NOT_FOUND.
Parâmetros
| Nome | Tipo | Detalhe |
|---|---|---|
| sqd_id | string | pathobrigatório |
| caller_account_id | string | queryobrigatório The calling account; must be a member |
| state | string, opcional | query PENDING_APPROVAL | EXECUTED | REJECTED | EXPIRED | FAILED |
| limit | integer | query |
| cursor | string, opcional | query |
Respostas
| Status | Corpo | Detalhe |
|---|---|---|
| 200 | SpendRequestListResponse | Resposta bem-sucedida |
| 422 | HTTPValidationError | Erro de validação |
/v1/squads/{sqd_id}/transactionsList a squad's activity (parent expenses, deposits, spends, settlements)
Squad activity timeline (RFC-018, SQ-18), oldest first. Accounting entries are grouped into one parent expense each (original total + per-member ``shares`` breakdown); ``?kind=ACCOUNTING`` returns just the expenses. ``?period=2026-07`` returns only that cycle's entries (B-SQ-04). Errors: 403 NOT_A_SQUAD_MEMBER, 404 SQUAD_NOT_FOUND.
Parâmetros
| Nome | Tipo | Detalhe |
|---|---|---|
| sqd_id | string | pathobrigatório |
| caller_account_id | string | queryobrigatório The calling account; must be a member |
| kind | string, opcional | query ACCOUNTING | FUNDED | SPEND | SETTLEMENT | CYCLE_SUMMARY | GOAL_ACHIEVED | SPEND_REQUEST |
| state | string, opcional | query |
| period | string, opcional | query Filter to one cycle, e.g. 2026-07 (B-SQ-04) |
| limit | integer | query |
| cursor | string, opcional | query |
Respostas
| Status | Corpo | Detalhe |
|---|---|---|
| 200 | SquadTransactionListResponse | Resposta bem-sucedida |
| 422 | HTTPValidationError | Erro de validação |
Esquemas
Os modelos que as operações acima aceitam e devolvem. Campos opcionais estão marcados como tal; um campo tipado como outro modelo está documentado sob o nome dele.
AccountInvitationListResponse
| Campo | Tipo | Detalhe |
|---|---|---|
| invitations | array de AccountInvitationOut |
AccountInvitationOut
One PENDING invite in the invitee inbox ``GET /v1/accounts/{acc_id}/invitations``. ``members`` is the squad's full current roster — the creator/owner, already-joined members (``status="ACTIVE"``), and other pending invitees (``role="INVITED"`` / ``status="PENDING"``) — so the invitee can see who's already in before accepting.
| Campo | Tipo | Detalhe |
|---|---|---|
| description | string, opcional | |
| emoji | string, opcional | |
| invited_at | string, opcional | |
| inviter_account_id | string, opcional | |
| members | array de SquadMemberOut | |
| name | string, opcional | |
| sqd_id | string | obrigatório |
| state | string, opcional |
AccountSquadListResponse
| Campo | Tipo | Detalhe |
|---|---|---|
| items | array de AccountSquadOut | |
| next_cursor | string, opcional |
AccountSquadOut
| Campo | Tipo | Detalhe |
|---|---|---|
| balance | SquadMoney | obrigatório |
| emoji | string, opcional | |
| goal | SquadGoalBlockOut, opcional | |
| image_url | string, opcional | |
| member_count | integer | obrigatório |
| name | string, opcional | |
| role | string, opcional | |
| sqd_id | string | obrigatório |
| state | string | obrigatório |
| template | string, opcional | |
| updated_at | string, opcional | |
| your_net_cents | integer | obrigatório |
HTTPValidationError
| Campo | Tipo | Detalhe |
|---|---|---|
| detail | array de ValidationError |
LedgerSummaryOut
| Campo | Tipo | Detalhe |
|---|---|---|
| as_of_seq | integer | obrigatório |
| positions | array de MemberPositionOut | |
| total_funded_in | integer | obrigatório |
| total_funded_out | integer | obrigatório |
| total_open_debt_cents | integer | obrigatório |
| vqbrl_outstanding | integer | obrigatório |
PendingSpendRequestsOut
Detail summary of open spend-requests awaiting approval (B-SQ-06) — the "Aprovar despesa" CTA-ladder signal. ``null`` when the squad has no policy.
| Campo | Tipo | Detalhe |
|---|---|---|
| count | integer | Padrão 0 |
| ids | array de string |
SettlementExecutionEndpoint
The exact call to discharge the caller's debts (POST /v1/squads/{id}/settle).
| Campo | Tipo | Detalhe |
|---|---|---|
| body_template | object | obrigatórioRequest body to POST verbatim to the live settle endpoint |
| method | string | obrigatórioHTTP method |
| url | string | obrigatórioSettle endpoint path |
SettlementPlanClaim
One open share where the caller is the creditor (informational — they cannot act).
| Campo | Tipo | Detalhe |
|---|---|---|
| debtor_account_id | string, opcional | Account that owes the caller (null if the pkh can't be resolved yet) |
| debtor_pkh | string | obrigatórioDebtor's 28-byte PubKeyHash |
| description | string | Human description of the originating expensePadrão "" |
| entry_seq | integer | obrigatórioAccounting entry sequence the share belongs to |
| share_cents | integer | obrigatórioAmount owed to the caller on this share, in cents |
| share_utxo_ref | string | obrigatórioOn-chain share UTxO ref (txhash#ix) |
SettlementPlanDebt
One open share where the caller is the debtor (something they must pay).
| Campo | Tipo | Detalhe |
|---|---|---|
| creditor_account_id | string, opcional | Account the caller owes (null if the pkh can't be resolved yet) |
| creditor_pkh | string | obrigatórioCreditor's 28-byte PubKeyHash |
| description | string | Human description of the originating expensePadrão "" |
| entry_seq | integer | obrigatórioAccounting entry sequence the share belongs to |
| share_cents | integer | obrigatórioAmount owed on this share, in cents |
| share_utxo_ref | string | obrigatórioOn-chain share UTxO ref (txhash#ix) |
SettlementPlanResponse
Response for GET /v1/accounts/{acc_id}/squads/{sqd_id}/settlement-plan.
| Campo | Tipo | Detalhe |
|---|---|---|
| as_of_iso | string | obrigatórioCONFIG updated_at ISO timestamp |
| as_of_seq | integer | obrigatórioCONFIG last_event_seq at read time |
| execution_endpoint | SettlementExecutionEndpoint, opcional | The settle call to clear your debts (null if you owe nothing) |
| message | string, opcional | Set when you owe nothing |
| sqd_id | string | obrigatórioSquad identifier |
| squad_rollup | SettlementSquadRollup | obrigatórioSquad-wide open-debt summary |
| you | string | obrigatórioThe caller account (the path account) |
| your_net_cents | integer | obrigatórioYour signed net in the squad |
| your_open_claims | array de SettlementPlanClaim | Open shares where you are the creditor (informational) |
| your_open_debts | array de SettlementPlanDebt | Open shares where you are the debtor |
| your_total_owed_cents | integer | obrigatórioSum of your_open_debts share amounts |
| your_total_owed_to_cents | integer | obrigatórioSum of your_open_claims share amounts |
SettlementSquadRollup
Squad-wide open-debt summary (for transparency).
| Campo | Tipo | Detalhe |
|---|---|---|
| members_not_net_zero | integer | obrigatórioCount of members whose net is non-zero |
| total_open_debt_cents | integer | obrigatórioSum of all open share amounts in the squad |
SimplifyEdgeOut
One debt edge: ``debtor`` owes ``creditor`` ``cents``. account_ids are the SQ-18 read-layer join (``None`` when a pkh has no registered account).
| Campo | Tipo | Detalhe |
|---|---|---|
| cents | integer | obrigatório |
| creditor_account_id | string, opcional | |
| creditor_pkh | string | obrigatório |
| debtor_account_id | string, opcional | |
| debtor_pkh | string | obrigatório |
SpendRequestListResponse
| Campo | Tipo | Detalhe |
|---|---|---|
| items | array de SquadSpendRequestOut | |
| next_cursor | string, opcional |
SquadCycleBlockOut
The ``cycle`` block on squad detail (B-SQ-04) — the currently-open monthly period.
| Campo | Tipo | Detalhe |
|---|---|---|
| carried_forward_cents | integer | Padrão 0 |
| closes_at | string, opcional | |
| contas | array de SquadContaOut | |
| period | string, opcional |
SquadDetailResponse
| Campo | Tipo | Detalhe |
|---|---|---|
| account_id | string, opcional | |
| address | string, opcional | |
| balance | SquadMoney | obrigatório |
| closed_at | string, opcional | |
| closed_by | string, opcional | |
| config_utxo_ref | string, opcional | |
| created_at | string, opcional | |
| created_by | string, opcional | |
| cycle | SquadCycleBlockOut, opcional | |
| frozen | boolean | Padrão false |
| goal | SquadGoalBlockOut, opcional | |
| last_event_seq | integer | obrigatório |
| ledger_summary | LedgerSummaryOut | obrigatório |
| links | object | |
| members | array de SquadMemberOut | |
| metadata | SquadMetadataOut | |
| name | string, opcional | |
| pending_spend_requests | PendingSpendRequestsOut, opcional | |
| rules | SquadRulesBlockOut, opcional | |
| simplified | boolean | Padrão false |
| sqd_id | string | obrigatório |
| state | string | obrigatório |
| vqbrl_policy_hash | string, opcional |
SquadGoalBlockOut
The ``goal`` block on squad reads (B-SQ-05) — the Meta template's finish line. ``funded_cents`` is the live pool balance (FUNDED in − spends − reclaims) and ``progress`` is ``funded_cents / target_amount.value`` clamped to ``[0, 1]``, both server-computed so every member sees the same numbers. ``achieved_at`` is sticky — set the first moment the pool reaches the target, kept even if the balance later dips. The whole block is ``null`` when the squad has no goal (existing squads unchanged).
| Campo | Tipo | Detalhe |
|---|---|---|
| achieved_at | string, opcional | |
| funded_cents | integer | obrigatório |
| progress | number | obrigatório |
| target_amount | SquadMoney | obrigatório |
| target_date | string, opcional |
SquadInvitationListResponse
| Campo | Tipo | Detalhe |
|---|---|---|
| invitations | array de SquadInvitationOut |
SquadInvitationOut
One PENDING invite in the owner-facing ``GET /v1/squads/{sqd_id}/invitations``.
| Campo | Tipo | Detalhe |
|---|---|---|
| created_at | string, opcional | |
| invitee_account_id | string, opcional | |
| invitee_pkh | string | obrigatório |
| inviter_account_id | string, opcional | |
| state | string | obrigatório |
| updated_at | string, opcional |
SquadListResponse
| Campo | Tipo | Detalhe |
|---|---|---|
| items | array de SquadSummaryOut | |
| next_cursor | string, opcional |
SquadMemberListResponse
| Campo | Tipo | Detalhe |
|---|---|---|
| members | array de SquadMemberOut |
SquadMemberOut
A roster entry. Active members carry ``status="ACTIVE"`` and ``joined_at``; pending invitees carry ``role="INVITED"``, ``status="PENDING"`` and the ``invited_at`` / ``invited_by_account_id`` fields (``joined_at`` is null until they accept). ``auto_collect`` (B-SQ-04 Assinatura) lists the member's auto-collect consents — ``null`` when they have none (a non-recurring squad's roster is unchanged).
| Campo | Tipo | Detalhe |
|---|---|---|
| auto_collect | array de SquadConsentOut, opcional | |
| invited_at | string, opcional | |
| invited_by_account_id | string, opcional | |
| joined_at | string, opcional | |
| member_account_id | string, opcional | |
| member_pkh | string, opcional | |
| quota | integer | Padrão 1 |
| role | string | obrigatório |
| status | string, opcional |
SquadMetadataOut
A squad's optional, off-chain display metadata. Mirrors the command-api write contract (``SquadMetadata``); every field is ``null`` when unset.
| Campo | Tipo | Detalhe |
|---|---|---|
| description | string, opcional | |
| emoji | string, opcional | |
| image_url | string, opcional | |
| location | SquadLocationOut, opcional | |
| template | string, opcional | |
| template_config | object, opcional |
SquadMoney
| Campo | Tipo | Detalhe |
|---|---|---|
| currency | string | obrigatório |
| value | integer | obrigatório |
SquadRulesBlockOut
The ``rules`` block on squad detail (B-SQ-06) — ``null`` when the squad has no policy (existing squads unchanged).
| Campo | Tipo | Detalhe |
|---|---|---|
| spend_approval | SpendApprovalPolicyOut | obrigatório |
SquadSimplifyPreviewResponse
``GET /v1/squads/{sqd_id}/simplify-preview`` — dry-run of debt simplification. ``before`` is the current gross open-debt graph; ``after`` is the minimal net set a ``POST /simplify-debts`` would produce. ``would_reduce`` is true iff executing would change the on-chain graph (false when it is already minimal).
| Campo | Tipo | Detalhe |
|---|---|---|
| after | array de SimplifyEdgeOut | |
| after_count | integer | obrigatório |
| before | array de SimplifyEdgeOut | |
| before_count | integer | obrigatório |
| sqd_id | string | obrigatório |
| would_reduce | boolean | obrigatório |
SquadSpendRequestOut
A spend-request with its full approval history — the transparency-list row (``GET /v1/squads/{sqd_id}/spend-requests``, B-SQ-06). ``state`` applies lazy expiry (a past-deadline pending request reads as EXPIRED).
| Campo | Tipo | Detalhe |
|---|---|---|
| amount | SquadMoney | obrigatório |
| approvals | array de SpendRequestApprovalOut | |
| approvals_required | integer | obrigatório |
| approvers | string, opcional | |
| created_at | string, opcional | |
| executed_at | string, opcional | |
| executed_obligation_id | string, opcional | |
| executed_tx_id | string, opcional | |
| expires_at | string, opcional | |
| failed_reason | string, opcional | |
| recipient_account_id | string, opcional | |
| reject_reason | string, opcional | |
| rejected_by | string, opcional | |
| requested_by | string, opcional | |
| spend_request_id | string | obrigatório |
| state | string | obrigatório |
SquadSummaryOut
Short-form row used in the global listing. Carries ``emoji``/``image_url`` so a client can render a squad avatar per row without fetching each detail.
| Campo | Tipo | Detalhe |
|---|---|---|
| balance | SquadMoney | obrigatório |
| emoji | string, opcional | |
| image_url | string, opcional | |
| member_count | integer | obrigatório |
| name | string, opcional | |
| sqd_id | string | obrigatório |
| state | string | obrigatório |
| updated_at | string, opcional |
SquadTransactionListResponse
| Campo | Tipo | Detalhe |
|---|---|---|
| items | array de SquadExpenseOut ou SquadTransactionOut ou SquadCycleSummaryOut ou SquadGoalAchievedOut ou SquadSpendRequestFeedOut | |
| next_cursor | string, opcional |
ValidationError
| Campo | Tipo | Detalhe |
|---|---|---|
| ctx | object | |
| input | não declarado | |
| loc | array de string ou integer | obrigatório |
| msg | string | obrigatório |
| type | string | obrigatório |