Obligations

5 operações em Quadra Command API 0.2.0.

GET/v1/obligations

List Obligations

List obligations with optional filters and cursor-based pagination.

Filters: state, resolution_outcome, rail_family, created_from, created_to, effective_from, effective_to (business time), match_key.client_reference, match_key.rail_ref.

Parâmetros

Nome	Tipo	Detalhe
state	string, opcional	query
resolution_outcome	string, opcional	query
rail	string, opcional	query
created_from	string, opcional	query
created_to	string, opcional	query
effective_from	string, opcional	query
effective_to	string, opcional	query
match_key.client_reference	string, opcional	query
match_key.rail_ref	string, opcional	query
limit	integer	query
cursor	string, opcional	query

Respostas

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

POST/v1/obligations

Create a Transfer Obligation

Create a transfer obligation between two Quadra accounts.

For INTERNAL / atomic transfers, the Hydra L2 transaction is submitted and the obligation is returned in state PENDING. Hydra confirms or rejects transactions asynchronously, so the caller must poll GET /v1/obligations/{id} to determine the final resolution.

Requires an Idempotency-Key header.

Parâmetros

Nome	Tipo	Detalhe
Idempotency-Key	string	headerobrigatório

Corpo da requisição

CreateObligationRequest — 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/obligations/{obligation_id}

Get an Obligation

Retrieve an obligation by its obligation ID.

Accepts both logical obligation IDs (``obl_*``) and legacy UTXO-based IDs (``txhash_index``).

State lifecycle: - OPEN — the obligation was created and the Hydra tx submitted, awaiting confirmation. - RESOLVED — the head-indexer confirmed or rejected the tx. Check resolution_outcome for SETTLED, FAILED, or CANCELED.

Parâmetros

Nome	Tipo	Detalhe
obligation_id	string	pathobrigatório

Respostas

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

PATCH/v1/obligations/{obligation_id}/match-keys

Update match keys on an Obligation

Add or update match_keys on an existing obligation.

Only `rail_ref` and `client_reference` are accepted keys. New values are merged with existing match_keys (overriding on conflict).

Parâmetros

Nome	Tipo	Detalhe
obligation_id	string	pathobrigatório

Corpo da requisição

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

Respostas

Status	Corpo	Detalhe
200	—	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/obligations/{obligation_id}/timeline

Get Obligation Timeline

Retrieve the full lifecycle timeline of an obligation.

Reconstructs events from all UTXOs (including spent ones) associated with the given obligation ID. Returns a chronologically-ordered list of state transition events.

Parâmetros

Nome	Tipo	Detalhe
obligation_id	string	pathobrigatório

Respostas

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

AmountField

Campo	Tipo	Detalhe
currency	string	obrigatórioISO 4217 currency code (e.g., 'BRL')
value	integer	obrigatórioAmount in centavos (e.g., 2500 = R$25.00)

CreateObligationRequest

Campo	Tipo	Detalhe
amount	AmountField	obrigatório
creditor	DebtorCreditor	obrigatório
debtor	DebtorCreditor	obrigatório
expected_settlement	ExpectedSettlement, opcional	Expected settlement window
match_keys	object, opcional	Keys for matching evidence to this obligation
metadata	object, opcional	Free-form metadata
rail	RailFamily	obrigatório

DebtorCreditor

Campo	Tipo	Detalhe
account_id	string, opcional	Quadra account ID (e.g., 'acc_...')
external_id	string, opcional	External entity identifier (for kind='external')
kind	string	obrigatórioEntity kind: 'account' or 'external'

ExpectedSettlement

Campo	Tipo	Detalhe
window	string	obrigatórioExpected settlement window (e.g., 'T+1', 'T+2')

HTTPValidationError

Campo	Tipo	Detalhe
detail	array de ValidationError

ObligationException

Campo	Tipo	Detalhe
description	string	obrigatórioHuman-readable description of the exception
evidence_amount	AmountDetail, opcional	Amount from the evidence that triggered this exception
matched_obligation_id	string, opcional	ID of the matched obligation (for AMOUNT_MISMATCH)
obligation_amount	AmountDetail, opcional	Amount of the matched obligation (for AMOUNT_MISMATCH)
trace_number	string, opcional	Trace number from the evidence
type	string	obrigatórioException type, e.g. AMOUNT_MISMATCH, UNMATCHED_SETTLEMENT

ObligationListItem

Campo	Tipo	Detalhe
adapter_ref	string, opcional
amount	integer, opcional
created_at	string, opcional
creditor_account_id	string, opcional
currency	string, opcional
debtor_account_id	string, opcional
dispatch_attempts	integer, opcional
dispatch_error	string, opcional
dispatch_status	string, opcional
dispatched_at	string, opcional
effective_at	string, opcional
obligation_id	string	obrigatório
pending_dispatch	boolean, opcional
rail	string, opcional
resolution_outcome	string, opcional
state	ObligationState	obrigatório

ObligationListResponse

Campo	Tipo	Detalhe
items	array de ObligationListItem	obrigatório
next_cursor	string, opcional

ObligationResponse

Campo	Tipo	Detalhe
adapter_ref	string, opcional
amount	integer, opcional
created_at	string, opcional
creditor_account_id	string, opcional
currency	string, opcional
debtor_account_id	string, opcional
dispatch_attempts	integer, opcional
dispatch_error	string, opcional
dispatch_status	string, opcional
dispatched_at	string, opcional
effective_at	string, opcional
evidence_id	string, opcional
exception	ObligationException, opcional
expected_settlement	object, opcional
external_id	string, opcional
indexed_at	string, opcional
match_keys	object, opcional
metadata	object, opcional
obligation_id	string	obrigatório
pending_dispatch	boolean, opcional
rail	string, opcional
resolution_outcome	string, opcional
resolution_reason	string, opcional
resolved_at	string, opcional
role	string, opcional
state	ObligationState	obrigatório
state_history	array de object, opcional
type	string, opcional
utxo_id	string, opcional

ObligationState

Um de: OPEN, FINAL, PENDING, EXCEPTION

ObligationTimelineResponse

Campo	Tipo	Detalhe
obligation_id	string	obrigatório
timeline	array de TimelineEvent	obrigatório

RailFamily

Um de: QUADRA, ACH, MOCK, PIX

TimelineEvent

Campo	Tipo	Detalhe
event	string	obrigatório
journal	TimelineJournalRef, opcional
transaction_id	string, opcional
updated_at	string	obrigatório

UpdateMatchKeysRequest

Campo	Tipo	Detalhe
match_keys	object	obrigatórioArbitrary key-value pairs for matching evidence to this obligation (all values must be strings)

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

← Quadra Command API Chamar no playground →