SonaCORE

Referência / Quadra Core API

Squads

10 operações em Quadra Core API 0.5.0.

GET/v1/accounts/{acc_id}/invitations

List 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

NomeTipoDetalhe
acc_idstringpathobrigatório

Respostas

StatusCorpoDetalhe
200AccountInvitationListResponseResposta bem-sucedida
422HTTPValidationErrorErro de validação
GET/v1/accounts/{acc_id}/squads

List 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

NomeTipoDetalhe
acc_idstringpathobrigatório
statestring, opcionalquery
limitintegerquery
cursorstring, opcionalquery

Respostas

StatusCorpoDetalhe
200AccountSquadListResponseResposta bem-sucedida
422HTTPValidationErrorErro de validação
GET/v1/accounts/{acc_id}/squads/{sqd_id}/settlement-plan

Get 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

NomeTipoDetalhe
acc_idstringpathobrigatório
sqd_idstringpathobrigatório

Respostas

StatusCorpoDetalhe
200SettlementPlanResponseResposta bem-sucedida
422HTTPValidationErrorErro de validação
GET/v1/squads

List 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

NomeTipoDetalhe
statestring, opcionalquery
limitintegerquery
cursorstring, opcionalquery

Respostas

StatusCorpoDetalhe
200SquadListResponseResposta bem-sucedida
422HTTPValidationErrorErro de validação
GET/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

NomeTipoDetalhe
sqd_idstringpathobrigatório
caller_account_idstringqueryobrigatório The calling account; must be a member

Respostas

StatusCorpoDetalhe
200SquadDetailResponseResposta bem-sucedida
422HTTPValidationErrorErro de validação
GET/v1/squads/{sqd_id}/invitations

List 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

NomeTipoDetalhe
sqd_idstringpathobrigatório
caller_account_idstringqueryobrigatório The calling account; must be a member

Respostas

StatusCorpoDetalhe
200SquadInvitationListResponseResposta bem-sucedida
422HTTPValidationErrorErro de validação
GET/v1/squads/{sqd_id}/members

Get 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

NomeTipoDetalhe
sqd_idstringpathobrigatório
caller_account_idstringqueryobrigatório The calling account; must be a member

Respostas

StatusCorpoDetalhe
200SquadMemberListResponseResposta bem-sucedida
422HTTPValidationErrorErro de validação
GET/v1/squads/{sqd_id}/simplify-preview

Preview 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

NomeTipoDetalhe
sqd_idstringpathobrigatório
caller_account_idstringqueryobrigatório The calling account; must be the OWNER

Respostas

StatusCorpoDetalhe
200SquadSimplifyPreviewResponseResposta bem-sucedida
422HTTPValidationErrorErro de validação
GET/v1/squads/{sqd_id}/spend-requests

List 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

NomeTipoDetalhe
sqd_idstringpathobrigatório
caller_account_idstringqueryobrigatório The calling account; must be a member
statestring, opcionalquery PENDING_APPROVAL | EXECUTED | REJECTED | EXPIRED | FAILED
limitintegerquery
cursorstring, opcionalquery

Respostas

StatusCorpoDetalhe
200SpendRequestListResponseResposta bem-sucedida
422HTTPValidationErrorErro de validação
GET/v1/squads/{sqd_id}/transactions

List 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

NomeTipoDetalhe
sqd_idstringpathobrigatório
caller_account_idstringqueryobrigatório The calling account; must be a member
kindstring, opcionalquery ACCOUNTING | FUNDED | SPEND | SETTLEMENT | CYCLE_SUMMARY | GOAL_ACHIEVED | SPEND_REQUEST
statestring, opcionalquery
periodstring, opcionalquery Filter to one cycle, e.g. 2026-07 (B-SQ-04)
limitintegerquery
cursorstring, opcionalquery

Respostas

StatusCorpoDetalhe
200SquadTransactionListResponseResposta bem-sucedida
422HTTPValidationErrorErro 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

CampoTipoDetalhe
invitationsarray 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.

CampoTipoDetalhe
descriptionstring, opcional
emojistring, opcional
invited_atstring, opcional
inviter_account_idstring, opcional
membersarray de SquadMemberOut
namestring, opcional
sqd_idstringobrigatório
statestring, opcional

AccountSquadListResponse

CampoTipoDetalhe
itemsarray de AccountSquadOut
next_cursorstring, opcional

AccountSquadOut

CampoTipoDetalhe
balanceSquadMoneyobrigatório
emojistring, opcional
goalSquadGoalBlockOut, opcional
image_urlstring, opcional
member_countintegerobrigatório
namestring, opcional
rolestring, opcional
sqd_idstringobrigatório
statestringobrigatório
templatestring, opcional
updated_atstring, opcional
your_net_centsintegerobrigatório

HTTPValidationError

CampoTipoDetalhe
detailarray de ValidationError

LedgerSummaryOut

CampoTipoDetalhe
as_of_seqintegerobrigatório
positionsarray de MemberPositionOut
total_funded_inintegerobrigatório
total_funded_outintegerobrigatório
total_open_debt_centsintegerobrigatório
vqbrl_outstandingintegerobrigató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.

CampoTipoDetalhe
countintegerPadrão 0
idsarray de string

SettlementExecutionEndpoint

The exact call to discharge the caller's debts (POST /v1/squads/{id}/settle).

CampoTipoDetalhe
body_templateobjectobrigatórioRequest body to POST verbatim to the live settle endpoint
methodstringobrigatórioHTTP method
urlstringobrigatórioSettle endpoint path

SettlementPlanClaim

One open share where the caller is the creditor (informational — they cannot act).

CampoTipoDetalhe
debtor_account_idstring, opcionalAccount that owes the caller (null if the pkh can't be resolved yet)
debtor_pkhstringobrigatórioDebtor's 28-byte PubKeyHash
descriptionstringHuman description of the originating expensePadrão ""
entry_seqintegerobrigatórioAccounting entry sequence the share belongs to
share_centsintegerobrigatórioAmount owed to the caller on this share, in cents
share_utxo_refstringobrigatórioOn-chain share UTxO ref (txhash#ix)

SettlementPlanDebt

One open share where the caller is the debtor (something they must pay).

CampoTipoDetalhe
creditor_account_idstring, opcionalAccount the caller owes (null if the pkh can't be resolved yet)
creditor_pkhstringobrigatórioCreditor's 28-byte PubKeyHash
descriptionstringHuman description of the originating expensePadrão ""
entry_seqintegerobrigatórioAccounting entry sequence the share belongs to
share_centsintegerobrigatórioAmount owed on this share, in cents
share_utxo_refstringobrigatórioOn-chain share UTxO ref (txhash#ix)

SettlementPlanResponse

Response for GET /v1/accounts/{acc_id}/squads/{sqd_id}/settlement-plan.

CampoTipoDetalhe
as_of_isostringobrigatórioCONFIG updated_at ISO timestamp
as_of_seqintegerobrigatórioCONFIG last_event_seq at read time
execution_endpointSettlementExecutionEndpoint, opcionalThe settle call to clear your debts (null if you owe nothing)
messagestring, opcionalSet when you owe nothing
sqd_idstringobrigatórioSquad identifier
squad_rollupSettlementSquadRollupobrigatórioSquad-wide open-debt summary
youstringobrigatórioThe caller account (the path account)
your_net_centsintegerobrigatórioYour signed net in the squad
your_open_claimsarray de SettlementPlanClaimOpen shares where you are the creditor (informational)
your_open_debtsarray de SettlementPlanDebtOpen shares where you are the debtor
your_total_owed_centsintegerobrigatórioSum of your_open_debts share amounts
your_total_owed_to_centsintegerobrigatórioSum of your_open_claims share amounts

SettlementSquadRollup

Squad-wide open-debt summary (for transparency).

CampoTipoDetalhe
members_not_net_zerointegerobrigatórioCount of members whose net is non-zero
total_open_debt_centsintegerobrigató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).

CampoTipoDetalhe
centsintegerobrigatório
creditor_account_idstring, opcional
creditor_pkhstringobrigatório
debtor_account_idstring, opcional
debtor_pkhstringobrigatório

SpendRequestListResponse

CampoTipoDetalhe
itemsarray de SquadSpendRequestOut
next_cursorstring, opcional

SquadCycleBlockOut

The ``cycle`` block on squad detail (B-SQ-04) — the currently-open monthly period.

CampoTipoDetalhe
carried_forward_centsintegerPadrão 0
closes_atstring, opcional
contasarray de SquadContaOut
periodstring, opcional

SquadDetailResponse

CampoTipoDetalhe
account_idstring, opcional
addressstring, opcional
balanceSquadMoneyobrigatório
closed_atstring, opcional
closed_bystring, opcional
config_utxo_refstring, opcional
created_atstring, opcional
created_bystring, opcional
cycleSquadCycleBlockOut, opcional
frozenbooleanPadrão false
goalSquadGoalBlockOut, opcional
last_event_seqintegerobrigatório
ledger_summaryLedgerSummaryOutobrigatório
linksobject
membersarray de SquadMemberOut
metadataSquadMetadataOut
namestring, opcional
pending_spend_requestsPendingSpendRequestsOut, opcional
rulesSquadRulesBlockOut, opcional
simplifiedbooleanPadrão false
sqd_idstringobrigatório
statestringobrigatório
vqbrl_policy_hashstring, 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).

CampoTipoDetalhe
achieved_atstring, opcional
funded_centsintegerobrigatório
progressnumberobrigatório
target_amountSquadMoneyobrigatório
target_datestring, opcional

SquadInvitationListResponse

CampoTipoDetalhe
invitationsarray de SquadInvitationOut

SquadInvitationOut

One PENDING invite in the owner-facing ``GET /v1/squads/{sqd_id}/invitations``.

CampoTipoDetalhe
created_atstring, opcional
invitee_account_idstring, opcional
invitee_pkhstringobrigatório
inviter_account_idstring, opcional
statestringobrigatório
updated_atstring, opcional

SquadListResponse

CampoTipoDetalhe
itemsarray de SquadSummaryOut
next_cursorstring, opcional

SquadMemberListResponse

CampoTipoDetalhe
membersarray 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).

CampoTipoDetalhe
auto_collectarray de SquadConsentOut, opcional
invited_atstring, opcional
invited_by_account_idstring, opcional
joined_atstring, opcional
member_account_idstring, opcional
member_pkhstring, opcional
quotaintegerPadrão 1
rolestringobrigatório
statusstring, opcional

SquadMetadataOut

A squad's optional, off-chain display metadata. Mirrors the command-api write contract (``SquadMetadata``); every field is ``null`` when unset.

CampoTipoDetalhe
descriptionstring, opcional
emojistring, opcional
image_urlstring, opcional
locationSquadLocationOut, opcional
templatestring, opcional
template_configobject, opcional

SquadMoney

CampoTipoDetalhe
currencystringobrigatório
valueintegerobrigatório

SquadRulesBlockOut

The ``rules`` block on squad detail (B-SQ-06) — ``null`` when the squad has no policy (existing squads unchanged).

CampoTipoDetalhe
spend_approvalSpendApprovalPolicyOutobrigató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).

CampoTipoDetalhe
afterarray de SimplifyEdgeOut
after_countintegerobrigatório
beforearray de SimplifyEdgeOut
before_countintegerobrigatório
sqd_idstringobrigatório
would_reducebooleanobrigató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).

CampoTipoDetalhe
amountSquadMoneyobrigatório
approvalsarray de SpendRequestApprovalOut
approvals_requiredintegerobrigatório
approversstring, opcional
created_atstring, opcional
executed_atstring, opcional
executed_obligation_idstring, opcional
executed_tx_idstring, opcional
expires_atstring, opcional
failed_reasonstring, opcional
recipient_account_idstring, opcional
reject_reasonstring, opcional
rejected_bystring, opcional
requested_bystring, opcional
spend_request_idstringobrigatório
statestringobrigató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.

CampoTipoDetalhe
balanceSquadMoneyobrigatório
emojistring, opcional
image_urlstring, opcional
member_countintegerobrigatório
namestring, opcional
sqd_idstringobrigatório
statestringobrigatório
updated_atstring, opcional

SquadTransactionListResponse

CampoTipoDetalhe
itemsarray de SquadExpenseOut ou SquadTransactionOut ou SquadCycleSummaryOut ou SquadGoalAchievedOut ou SquadSpendRequestFeedOut
next_cursorstring, opcional

ValidationError

CampoTipoDetalhe
ctxobject
inputnão declarado
locarray de string ou integerobrigatório
msgstringobrigatório
typestringobrigatório