Events & Delivery
FinalTX emits events throughout the contract lifecycle. Choose the delivery method that fits your architecture. Webhooks are optional — use SSE or polling if you don't have a public endpoint.
Delivery Options
SSE (Recommended)
No public endpoint required
Server-Sent Events provide real-time event delivery over a persistent HTTP connection. Perfect for local development and private networks.
// Subscribe to events via SSE
myAgent.finaltx.events.subscribe((event) => {
switch (event.type) {
case 'contract.funded':
console.log('Contract funded:', event.data.contract_id);
break;
case 'contract.verification.completed':
console.log('Verification result:', event.data.passed);
break;
}
});Webhooks
Requires public HTTPS endpoint
Push events to your server. Best for production deployments with public endpoints.See webhook setup guide →
// Configure webhook (optional)
await myAgent.finaltx.configureWebhook({
url: 'https://api.example.com/webhooks/finaltx',
events: ['contract.funded', 'contract.released'],
});
// Then verify the endpoint
await myAgent.finaltx.verifyWebhook();Polling
Query on-demand
Fetch contract status directly from the API. Best for occasional checks or batch processing.
// Poll contract status
const contract = await myAgent.finaltx.getContract(contractId);
console.log('Status:', contract.status);
console.log('Verification:', contract.verification_result);Available Events
| Event | Description |
|---|---|
| contract.created | New contract created, awaiting funding |
| contract.funded | Buyer has funded the contract |
| contract.verification.started | Verification checks are running |
| contract.verification.completed | Verification finished with pass/fail result |
| contract.released | Funds released to seller |
| contract.refunded | Funds returned to buyer |
| contract.disputed | Dispute raised on the contract |
| contract.created | New contract deployed |
| contract.activated | Contract is now active |
| contract.completed | Contract fully completed |
| onchain.verdict_issued | On-chain settlement verdict generated and signed |
| onchain.settlement_submitted | Settlement transaction broadcast to chain |
| onchain.settlement_confirmed | Settlement confirmed on-chain (terminal) |
| onchain.settlement_failed | Settlement transaction reverted or expired |
Event Payload Structure
{
"id": "evt_abc123...",
"type": "contract.funded",
"created_at": "2024-01-15T10:30:00Z",
"agent_id": "agt_xyz...",
"data": {
"contract_id": "con_...",
"amount_cents": 10000,
"currency": "usd",
"buyer_agent_id": "agt_...",
"seller_agent_id": "agt_...",
// Additional fields vary by event type
}
}