Accounts

7 operações em Quadra Core API 0.5.0.

GET/v1/accounts

Search Accounts

Parâmetros

Nome	Tipo	Detalhe
query	string, opcional	query
type	string, opcional	query
status	string, opcional	query
currency	string, opcional	query
owner_party_id	string, opcional	query
is_frozen	boolean, opcional	query
limit	integer	query
cursor	string, opcional	query

Respostas

Status	Corpo	Detalhe
200	AccountSearchResponseOut	Resposta bem-sucedida
422	HTTPValidationError	Erro de validação

POST/v1/accounts

Create an Account

Create a new account.

Creates a ledger container owned by a party, used to anchor intents/obligations and (later) postings. Generates Cardano keys and stores them with envelope encryption.

Returns: 201 Created with full Account object

Raises: 404: owner_party_id doesn't exist 422: Invalid type or currency 500: Internal error during account creation

Parâmetros

Nome	Tipo	Detalhe
Idempotency-Key	string	headerobrigatório

Corpo da requisição

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

Respostas

Status	Corpo	Detalhe
201	AccountResponse	Resposta bem-sucedida
422	HTTPValidationError	Erro de validação

GET/v1/accounts/{account_id}

Get an Account

Get an account by ID.

Returns: Account object if found

Raises: 404: Account not found

Parâmetros

Nome	Tipo	Detalhe
account_id	string	pathobrigatório

Respostas

Status	Corpo	Detalhe
200	AccountWithPaymentMethodsResponse	Resposta bem-sucedida
422	HTTPValidationError	Erro de validação

GET/v1/accounts/{account_id}/balance

Get Account Balance

Get the balance of an account by summing its UTXOs.

Returns aggregated balance per currency with optional obligation details. Under ``as_of``/``as_of_seq`` the balance is reconstructed by journal replay (RFC-009 §7.1): the response echoes the resolved cut in ``as_of``, adds a ``reconstruction`` block, and returns ``committed_to_products/squads`` as [] (live-only composition). EXTERNAL accounts keep the live short-circuit shape (their custody set is empty at every cut).

Parâmetros

Nome	Tipo	Detalhe
account_id	string	pathobrigatório
asset	string, opcional	query Filter by currency symbol (e.g. BRL)
include	string, opcional	query Comma-separated includes (e.g. obligations; positions with as_of)
obligations_state	string, opcional	query Filter obligations by state
as_of	string, opcional	query Point-in-time cut: ISO-8601 instant (commit-time basis, LaaS-03)
as_of_seq	integer, opcional	query Point-in-time cut: journal sequence number (mutually exclusive with as_of)

Respostas

Status	Corpo	Detalhe
200	AccountBalanceResponse	Resposta bem-sucedida
422	HTTPValidationError	Erro de validação

POST/v1/accounts/{account_id}/payment-methods

Bind a Payment Method

Bind a payment method to an account.

Accepts a typed payload with rail, scheme, and coordinates. Currently supports ACH; extensible to PIX, WIRE, SEPA.

Parâmetros

Nome	Tipo	Detalhe
account_id	string	pathobrigatório
Idempotency-Key	string	headerobrigatório

Corpo da requisição

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

Respostas

Status	Corpo	Detalhe
201	—	Resposta bem-sucedidaO contrato não declara um modelo para esta resposta, então a forma dela não está documentada aqui. Um roteiro de demonstração mostra a forma que ela realmente devolve.
422	HTTPValidationError	Erro de validação

GET/v1/accounts/{account_id}/statement

Formal account statement for a date range

A synchronous, effective-dated statement built from the journal-entry read model (LaaS-20): custody-layer net legs, one line per confirmed transaction.

Periods are América/São_Paulo accounting days over *effective* time (fixed −03:00); DR→CREDIT, CR→DEBIT (DR = value in). Opening = cumulative net from the opening epoch to ``from``; closing = opening + period net. The ``reconciliation`` block cross-checks closing against the live balance and is emitted only when ``to`` is today or later. MEMO-layer (squad vQBRL) accounting entries are excluded — this is a custody-layer statement.

``format=pdf`` is rejected (400): PDF rendering is BFF/mobile presentation territory, not Core.

Raises: 404: unknown or hidden FAUCET account (before any other validation) 400: from > to, ranges over 366 days, or unsupported format

Parâmetros

Nome	Tipo	Detalhe
account_id	string	pathobrigatório
from	string	queryobrigatório Inclusive start accounting day (yyyy-mm-dd, América/São_Paulo)
to	string	queryobrigatório Inclusive end accounting day (yyyy-mm-dd, América/São_Paulo)
format	string	query Response format: json (default) or csv

Respostas

Status	Corpo	Detalhe
200	StatementResponse	Resposta bem-sucedida
422	HTTPValidationError	Erro de validação

GET/v1/accounts/{account_id}/transactions

List Account Transactions

List an account's transactions, newest first.

Returns a reverse-chronological, cursor-paginated feed of the economic events that touched the account — deposits and transfers (obligations), SafeSwap escrow movements, and squad operations that move value into or out of this account's base balance (funding a squad, receiving a squad spend, settling a squad share) — each projected from this account's perspective as a CREDIT or DEBIT. Squad-internal bookkeeping (accounting shares) is not a base-balance movement and does not appear here.

When ``effective_from``/``effective_to`` are given, the feed is ordered and filtered by business time (``effective_at``) instead of recording time — a distinct query mode with its own cursors; cursors from one mode are rejected in the other.

Parâmetros

Nome	Tipo	Detalhe
account_id	string	pathobrigatório
limit	integer	query
cursor	string, opcional	query
effective_from	string, opcional	query Inclusive lower bound on effective_at (ISO 8601)
effective_to	string, opcional	query Inclusive upper bound on effective_at (ISO 8601)

Respostas

Status	Corpo	Detalhe
200	TransactionListResponse	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.

AccountBalanceResponse

Top-level response for GET /v1/accounts/{account_id}/balance.

Campo	Tipo	Detalhe
account_id	string	obrigatórioQuadra account identifier
as_of	string	obrigatórioISO 8601 timestamp of the balance snapshot
assets	array de AssetEntry	obrigatórioAsset balances
banking_coordinates	BankingCoordinates, opcional	Banking coordinates from ACH payment methods
committed_to_products	array de CommittedProductSummary	Open product-instance commitments where this account is the locker
committed_to_squads	array de CommittedSquadSummary	The account's position in each OPEN squad it belongs to (RFC-018, SQ-16)
consistency	BalanceConsistency	obrigatórioConsistency metadata
display_name	string, opcional	Owner party display name
positions	array de ReconstructedPosition, opcional	Reconstructed position set (only under as_of with include=positions)
reconstruction	Reconstruction, opcional	Present only under as_of/as_of_seq: commit-time reconstruction provenance
type	string	obrigatórioAccount type (CUSTOMER, ASSET, TRANSIT, REVENUE, EXCEPTION)
unit	string	Unit of balance amountsPadrão `"cents"`

AccountCreateRequest

Request body for creating a new account.

Campo	Tipo	Detalhe
currency	string	obrigatórioISO 4217 currency code (e.g., BRL)
metadata	object, opcional	Optional free-form metadata (max 8KB)
owner_party_id	string	obrigatórioParty ID that owns this account
type	AccountType	obrigatórioAccount type: CUSTOMER, ASSET, TRANSIT, REVENUE, or EXCEPTION

AccountResponse

Response model for account operations.

Campo	Tipo	Detalhe
address	string, opcional	Cardano address for this account
created_at	string	obrigatórioISO 8601 timestamp of creation
created_by	string	obrigatórioAPI client that created this account
currency	string	obrigatórioISO 4217 currency code
id	string	obrigatórioUnique account identifier (acc_...)
is_frozen	boolean	obrigatórioWhether the account is frozen for operations
metadata	object, opcional	Free-form metadata
owner_party_id	string	obrigatórioParty ID that owns this account
status	AccountStatus	obrigatórioAccount lifecycle status
type	AccountType	obrigatórioAccount type
updated_at	string	obrigatórioISO 8601 timestamp of last update

AccountSearchItemOut

Single account item in search results.

Campo	Tipo	Detalhe
address	string, opcional	Cardano address for this account
currency	string, opcional	ISO 4217 currency code
id	string	obrigatórioUnique account identifier (acc_...)
is_frozen	boolean, opcional	Whether the account is frozen for operations
owner_party_id	string, opcional	Party ID that owns this account
status	string, opcional	Account lifecycle status
type	string, opcional	Account type

AccountSearchResponseOut

Paginated list of accounts.

Campo	Tipo	Detalhe
data	array de AccountSearchItemOut	obrigatório
next_cursor	string, opcional

AccountStatus

Account lifecycle status.

Um de: ACTIVE, CLOSED

AccountType

Account type enum - controls what operations are allowed.

Um de: ASSET, TRANSIT, REVENUE, EXCEPTION, CUSTOMER, EXTERNAL, GUEST, SQUAD

AccountWithPaymentMethodsResponse

Account response including external payment methods.

Campo	Tipo	Detalhe
address	string, opcional	Cardano address for this account
created_at	string	obrigatórioISO 8601 timestamp of creation
created_by	string	obrigatórioAPI client that created this account
currency	string	obrigatórioISO 4217 currency code
external_payment_methods	array de PaymentMethodResponse, opcional	List of external payment methods bound to this account
id	string	obrigatórioUnique account identifier (acc_...)
is_frozen	boolean	obrigatórioWhether the account is frozen for operations
metadata	object, opcional	Free-form metadata
owner_party_id	string	obrigatórioParty ID that owns this account
promoted_to_account_id	string, opcional	If this GUEST/EXTERNAL account was promoted to a CUSTOMER account, the new account_id (RFC-021 §3.4 / LaaS-17); queries follow the pointer to reconcile history
status	AccountStatus	obrigatórioAccount lifecycle status
type	AccountType	obrigatórioAccount type
updated_at	string	obrigatórioISO 8601 timestamp of last update

AssetEntry

A single asset in the balance response.

Campo	Tipo	Detalhe
balances	AssetBalances	obrigatórioBalance breakdown
obligations	array de ObligationSummary, opcional	Obligation details (when include=obligations)
symbol	string	obrigatórioCurrency symbol (e.g. BRL)

BalanceConsistency

Consistency metadata for the balance snapshot.

Campo	Tipo	Detalhe
ledger_version	integer	obrigatórioLedger version number
snapshot_id	string	obrigatórioHash-based snapshot identifier

BankingCoordinates

Banking coordinates extracted from ACH payment methods.

Campo	Tipo	Detalhe
account_number	string	obrigatórioBank account number
routing_number	string	obrigatórioABA routing number

Capabilities

Transaction capabilities for a payment method.

Campo	Tipo	Detalhe
originate_debit	boolean	obrigatórioCan originate debit pulls
receive_credit	boolean	obrigatórioCan receive credit transfers
supports_returns	boolean	obrigatórioWhether returns are supported

CommittedProductSummary

Per-product roll-up of an account's open commitments.

Campo	Tipo	Detalhe
instances	array de CommittedInstanceSummary	Open instances contributing to the total
product_id	string	obrigatórioProduct identifier (e.g. quadra-escrow)
total_committed_value	integer	obrigatórioSum of amount.value across open instances for this account

CommittedSquadSummary

The account's position in one OPEN squad it is a member of (RFC-018, SQ-16).

Campo	Tipo	Detalhe
funded_in_cents	integer	obrigatórioQBRL the account currently holds in the squad's funded pool
has_open_debts	boolean	obrigatórioTrue iff your_owed_cents > 0 (something to settle)
name	string, opcional	Squad display name
role	string, opcional	The account's role in the squad (OWNER\|SPENDER)
sqd_id	string	obrigatórioSquad identifier
state	string	obrigatórioSquad state (OPEN)
your_net_cents	integer	obrigatórioSigned net: positive = owed to you; negative = you owe
your_owed_cents	integer	obrigatórioSum of the account's open debt shares (what it must pay)
your_owed_to_cents	integer	obrigatórioSum of open shares where the account is the creditor

Directionality

Which directions the payment method supports.

Campo	Tipo	Detalhe
inbound	boolean	obrigatórioCan receive funds
outbound	boolean	obrigatórioCan send funds

HTTPValidationError

Campo	Tipo	Detalhe
detail	array de ValidationError

PaymentMethodMode

How the payment method was provisioned.

Um de: EXTERNAL_ALLOCATION, CUSTOMER_LINKED, PROVIDER_MANAGED, VIRTUAL_ADDRESS

PaymentMethodRequest

Request body for binding a payment method to an account.

Campo	Tipo	Detalhe
capabilities	Capabilities	obrigatórioTransaction capabilities
coordinates	USACHCoordinates ou BRMockCoordinates ou BRPixKeyCoordinates	obrigatórioRail-specific coordinates
directionality	Directionality	obrigatórioSupported fund directions
metadata	object, opcional	Optional free-form metadata (max 8KB)
mode	PaymentMethodMode	obrigatórioHow the payment method was provisioned
provider	ProviderInfo	obrigatórioProvider information
rail	Rail	obrigatórioPayment rail (ACH, PIX, WIRE, etc.)
scheme	Scheme	obrigatórioPayment scheme within the rail
status	PaymentMethodStatus	obrigatórioInitial status
verification	Verification	obrigatórioVerification state

PaymentMethodResponse

Response for a payment method with masked coordinates.

Campo	Tipo	Detalhe
account_id	string	obrigatórioAccount this payment method is bound to
capabilities	Capabilities	obrigatórioTransaction capabilities
coordinates	USACHCoordinatesResponse ou BRMockCoordinatesResponse ou BRPixKeyCoordinatesResponse	obrigatórioMasked coordinates
created_at	string	obrigatórioISO 8601 creation timestamp
directionality	Directionality	obrigatórioSupported fund directions
metadata	object, opcional	Free-form metadata
mode	PaymentMethodMode	obrigatórioProvisioning mode
payment_method_id	string	obrigatórioUnique payment method identifier
provider	ProviderInfo	obrigatórioProvider information
rail	Rail	obrigatórioPayment rail
scheme	Scheme	obrigatórioPayment scheme
status	PaymentMethodStatus	obrigatórioPayment method status
updated_at	string	obrigatórioISO 8601 last update timestamp
verification	Verification	obrigatórioVerification state

PaymentMethodStatus

Payment method lifecycle status.

Um de: ACTIVE, PENDING_VERIFICATION, SUSPENDED, CLOSED

ProviderInfo

Provider information for externally allocated payment methods.

Campo	Tipo	Detalhe
provider_id	string	obrigatórioUnique identifier for the provider
type	ProviderType	obrigatórioProvider type: SPONSOR_BANK or BAAS_PROVIDER

Rail

Payment rail.

Um de: ACH, PIX, EFT_CA, WIRE, SEPA, MOCK

ReconstructedPosition

One position of the reconstructed set (balance ``include=positions`` under as_of).

Campo	Tipo	Detalhe
asset	string, opcional
position_id	string	obrigatório
state	string, opcional
value	integer	obrigatório

Reconstruction

Provenance block for an as-of balance reconstruction (D1: commit-time basis).

Campo	Tipo	Detalhe
as_of_seq	integer	obrigatório
basis	string	Padrão `"commit_time"`
entries_replayed	integer	obrigatório
journal_head_seq	integer	obrigatório

Scheme

Payment scheme within a rail.

Um de: US_ACH, BR_PIX_KEY, BR_BANK_ACCOUNT, CA_TRANSIT, BR_MOCK

StatementLine

One netted line per confirmed transaction (custody layer, this account).

Campo	Tipo	Detalhe
accounting_day	string	obrigatórioAmérica/São_Paulo (−03:00) accounting day the tx applies to
amount_cents	integer	obrigatórioAbsolute net amount for this tx in minor units
asset	string	obrigatórioCustody asset (QBRL)
correlation	StatementCorrelation	sqd_id / swp_id / evidence_id where applicable
direction	"CREDIT" \| "DEBIT"	obrigatórioCREDIT = money in (DR), DEBIT = money out (CR)
effective_at	string	obrigatórioBusiness-time instant the tx applies to (ISO 8601)
event_kind	string, opcional	Entry-set classification (TRANSFER_INTERNAL, DEPOSIT, SQUAD_SETTLE, ...)
obligation_ids	array de string	Backing obligations (obl_*)
tx_id	string	obrigatórioConfirmed Hydra transaction hash (groups feed legs; sum-per-tx_id)

StatementPeriod

The requested statement window, echoed back with its accounting timezone.

Campo	Tipo	Detalhe
from	string	obrigatórioInclusive start accounting day (yyyy-mm-dd, América/São_Paulo)
timezone	string	Accounting-day timezone (fixed −03:00, no DST)Padrão `"America/Sao_Paulo"`
to	string	obrigatórioInclusive end accounting day (yyyy-mm-dd, América/São_Paulo)

StatementReconciliation

Live-balance cross-check; emitted only for a period ending today or later.

Campo	Tipo	Detalhe
live_balance_cents	integer	obrigatórioCurrent available balance (sum of unspent custody UTxOs)
matches	boolean	obrigatórioclosing_balance_cents == live_balance_cents (RFC-025 §8 guarantee)

StatementResponse

A formal account statement for a date range (json; csv = one row per line).

Campo	Tipo	Detalhe
account_id	string	obrigatórioAccount the statement is for
closing_balance_cents	integer	obrigatórioopening_balance_cents + period net
fees	não declarado, opcional	Reserved (null): no fee primitive exists in Core yet
holds	não declarado, opcional	Reserved (null): hold balances are not surfaced in the statement yet
lines	array de StatementLine	obrigatórioPer-tx netted lines, chronological (effective time)
opening_balance_cents	integer	obrigatórioCumulative net from the opening epoch up to (excluding) 'from'
period	StatementPeriod	obrigatórioThe requested window + accounting timezone
reconciliation	StatementReconciliation, opcional	Present only when 'to' ≥ today (São Paulo)
totals	StatementTotals	obrigatórioPeriod aggregates

StatementTotals

Period aggregates over the statement lines.

Campo	Tipo	Detalhe
credits_cents	integer	obrigatórioSum of CREDIT line amounts
debits_cents	integer	obrigatórioSum of DEBIT line amounts
line_count	integer	obrigatórioNumber of statement lines
net_cents	integer	obrigatóriocredits_cents − debits_cents

TransactionItem

A single entry in an account's transaction feed.

Campo	Tipo	Detalhe
amount	integer	obrigatórioAmount in minor units (cents)
counterparty_account_id	string, opcional	The other account in the event, if any
counterparty_display_name	string, opcional	Owner party display name of the counterparty (best-effort)
created_at	string	obrigatórioISO 8601 event timestamp
currency	string	obrigatórioISO 4217 currency code
direction	TransactionDirection	obrigatórioCREDIT (value in) or DEBIT (value out) for this account
effective_at	string	obrigatórioISO 8601 business-time instant this entry applies to (effective dating). Equals created_at unless the rail or an operator asserted a different business date (e.g. a backdated devolução).
id	string	obrigatórioReference id of the underlying event (obl_* or swp_*)
rail	string, opcional	Payment rail family (QUADRA, ACH, ...) for obligation events
ref_kind	string	obrigatórioKind of underlying event: 'obligation' or 'safeswap'
status	TransactionStatus	obrigatórioCurrent settlement status
tx_id	string, opcional	On-chain transaction id that produced this entry. Entries sharing one tx_id are legs of a single transaction (e.g. several squad debts settled in one settle tx) — group by it to render them as one transaction.
type	string	obrigatórioEvent type: DEPOSIT, TRANSFER, SAFESWAP_LOCKED, SAFESWAP_RELEASED, SAFESWAP_REFUNDED

TransactionListResponse

Paginated, reverse-chronological transaction feed for an account.

Campo	Tipo	Detalhe
items	array de TransactionItem	obrigatórioActivity entries, newest first
next_cursor	string, opcional	Cursor for the next page; null when no more pages
unit	string	Unit of transaction amountsPadrão `"cents"`

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

Verification

Verification state for a payment method.

Campo	Tipo	Detalhe
status	VerificationStatus	obrigatórioCurrent verification status

← Quadra Core API Chamar no playground →