> ## Documentation Index > Fetch the complete documentation index at: https://docs.zopay.cash/llms.txt > Use this file to discover all available pages before exploring further. # List events > GET /events — log durable de eventos emitidos para tu organización. Devuelve los eventos del log canónico, más recientes primero. Es la superficie **pull** de la entrega de eventos; los webhooks son la superficie **push** de los mismos datos. Concepto y diagrama en [Events](/api-reference/events). ## OpenAPI ````yaml GET /events openapi: 3.1.0 info: title: ZoPay Connect API description: >- B2B partner API for crypto custody, deposits, and payouts. Authenticate every request with a Bearer token (``sk_live_…`` for production, ``sk_test_…`` for sandbox). version: v1 servers: - url: https://api.zopay.cash/connect/v1 description: Production - url: https://dev.api.zopay.cash/connect/v1 description: Development security: - BearerAuth: [] tags: - name: capabilities description: >- Static product catalog: which assets, networks, and fiat valuations this tenant can use. Poll on app startup to drive every UI surface (network pickers, fee warnings, fiat selection). - name: addresses description: >- Per-user deposit addresses. Mint with ``external_ref`` to attribute to one of your users; omit for a tenant-treasury (pooled) address. - name: payment-intents description: >- Single-use payment requests. Mint an intent for a specific amount + currency set; we expand it to per-network deposit addresses. Pass ``external_ref`` to attribute the intent to one of your users for downstream webhook reconciliation. - name: balances description: >- Per-user or tenant-wide balance snapshot with multi-fiat valuation (USD, PEN, EUR, MXN, ARS, COP, DOP). - name: transactions description: >- Unified ledger covering deposits, payouts, internal transfers, and (after Phase 4) conversions and ramps. - name: payouts description: >- Outbound money movement: get a signed quote, then execute it. Quote IDs are single-use and expire in 60s. - name: conversions description: '[Coming soon] Crypto-to-crypto conversions.' - name: ramps description: '[Coming soon] Fiat <-> crypto hosted-checkout sessions.' - name: webhooks description: '[Coming soon] Subscribe to event streams + replay past events.' - name: health description: >- Auth + connectivity probe. Use to validate your API key works before depending on a priced endpoint. - name: test-helpers description: >- Sandbox-only simulators. Let you exercise webhook handlers and downstream state transitions without real testnet activity. Routes return 404 to ``sk_live_…`` keys. paths: /events: get: tags: - events summary: List events description: >- Cursor-paginated list of events for this tenant. Every partner-visible side-effect (intent completions today; address deposits and more in future PRs) appears here as a single row. The same payload is delivered to your webhook URL if configured; this endpoint is the durable log you can query at any time, replay from (PR 5), or use to reconcile missed deliveries without contacting support. Filters compose: ``type`` + ``related_to`` returns events matching BOTH. Unknown ``type`` values 400 (the v1 vocabulary is documented in CONNECT.md). ``livemode`` omitted returns both modes; pass ``true`` or ``false`` to scope to one. Date range is inclusive on both ends. operationId: list_events_events_get parameters: - name: type in: query required: false schema: anyOf: - type: string - type: 'null' description: >- Comma-separated list of event types to include. v1 vocabulary: ``payment_intent.completed``, ``address.deposit.received``. Unknown values return 400 ``invalid_type``. title: Type description: >- Comma-separated list of event types to include. v1 vocabulary: ``payment_intent.completed``, ``address.deposit.received``. Unknown values return 400 ``invalid_type``. - name: related_to in: query required: false schema: anyOf: - type: string - type: 'null' description: >- UUID of the principal object the event is about. Useful for ``show me every event for this intent``; pass the intent id (or future address id, etc.) here. Single-value -- to query across N principals make N requests. title: Related To description: >- UUID of the principal object the event is about. Useful for ``show me every event for this intent``; pass the intent id (or future address id, etc.) here. Single-value -- to query across N principals make N requests. - name: livemode in: query required: false schema: anyOf: - type: string - type: 'null' description: >- ``true`` / ``false`` / omit. Filters by the event's livemode column verbatim. Omit to include both modes. title: Livemode description: >- ``true`` / ``false`` / omit. Filters by the event's livemode column verbatim. Omit to include both modes. - name: from in: query required: false schema: anyOf: - type: string - type: 'null' description: >- Inclusive lower bound on ``created_at`` (ISO 8601 date or datetime; naive input is treated as UTC). title: From description: >- Inclusive lower bound on ``created_at`` (ISO 8601 date or datetime; naive input is treated as UTC). - name: to in: query required: false schema: anyOf: - type: string - type: 'null' description: >- Inclusive upper bound on ``created_at`` (ISO 8601 date or datetime; naive input is treated as UTC). title: To description: >- Inclusive upper bound on ``created_at`` (ISO 8601 date or datetime; naive input is treated as UTC). - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' description: >- Opaque continuation token from a previous response's ``cursor`` field. Omit to fetch the first page. title: Cursor description: >- Opaque continuation token from a previous response's ``cursor`` field. Omit to fetch the first page. - name: limit in: query required: false schema: type: integer maximum: 200 minimum: 1 description: Max rows to return (server clamps at 200). default: 50 title: Limit description: Max rows to return (server clamps at 200). responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ConnectEventsListResponse' '400': description: >- Invalid request. The body or query parameters failed validation. ``error.code`` names the specific failure (e.g. ``invalid_request``, ``catalog_invalid``, ``min_usdt_amount_requires_solana``); ``error.param`` names the offending field when applicable. content: application/json: schema: $ref: '#/components/schemas/ConnectErrorEnvelope' '401': description: >- Authentication failed. ``error.code`` distinguishes ``authentication_required`` (missing / malformed / unknown key) from ``expired_credential`` (key matched but past its ``expires_at``). Rotate the key in the admin panel for the latter. content: application/json: schema: $ref: '#/components/schemas/ConnectErrorEnvelope' '403': description: >- The key is valid but lacks permission for this endpoint. ``error.code`` is ``forbidden_scope`` when the key is missing a scope; ``account_pending_approval`` when the org is not yet active for Connect. content: application/json: schema: $ref: '#/components/schemas/ConnectErrorEnvelope' '404': description: >- Resource not found in this tenant. Same envelope shape is returned for genuinely-missing IDs and for cross-tenant accesses -- existence under other tenants is not leakable. content: application/json: schema: $ref: '#/components/schemas/ConnectErrorEnvelope' '409': description: >- Conflict. Most commonly ``idempotency_conflict`` -- the same ``Idempotency-Key`` was reused with a different body. Generate a fresh key or replay the original body. content: application/json: schema: $ref: '#/components/schemas/ConnectErrorEnvelope' '422': description: >- Validation failed. Runtime translates FastAPI / Pydantic validation errors into the same Connect envelope you see on 400s; this status is emitted when the request shape is structurally wrong (missing required field, wrong type). content: application/json: schema: $ref: '#/components/schemas/ConnectErrorEnvelope' '429': description: >- Rate limited. Back off and retry. ``error.code`` is ``rate_limited``; per-key throughput is documented via ``rate_limit_rps`` on the API key. content: application/json: schema: $ref: '#/components/schemas/ConnectErrorEnvelope' '500': description: >- Internal server error. ``error.code`` is ``internal_error``. The request can usually be safely retried with the same ``Idempotency-Key``. content: application/json: schema: $ref: '#/components/schemas/ConnectErrorEnvelope' '501': description: >- Endpoint is declared in the router but its implementation has not shipped yet (``error.code = not_yet_available``). Pinned in the schema so SDK generators emit the endpoint with a typed error rather than skipping it. content: application/json: schema: $ref: '#/components/schemas/ConnectErrorEnvelope' security: - BearerAuth: [] components: schemas: ConnectEventsListResponse: properties: data: items: $ref: '#/components/schemas/ConnectEventLine' type: array title: Data has_more: type: boolean title: Has More description: >- True iff at least one more row exists past this page. Computed by fetching ``limit + 1`` rows server-side; if the SQL returns ``limit + 1``, we slice to ``limit`` and set has_more=True. cursor: anyOf: - type: string - type: 'null' title: Cursor description: >- Opaque continuation token. Pass back as ``?cursor=...`` to fetch the next page; None on the last page. type: object required: - has_more title: ConnectEventsListResponse description: |- Paginated list response, same envelope as the other Connect " list endpoints. ConnectErrorEnvelope: properties: error: $ref: '#/components/schemas/ConnectErrorBody' description: >- Error details. Always present on a non-2xx response from /connect/v1. type: object required: - error title: ConnectErrorEnvelope description: |- Top-level wrapper for every /connect/v1 failure response. Wire shape:: {"error": {"type": ..., "code": ..., "message": ..., ...}} The wrapper is intentional: it keeps error bodies syntactically distinct from success bodies, so polymorphic partner code paths that read the same JSON for both states can branch on the presence of the ``error`` key. ConnectEventLine: properties: id: type: string title: Id description: >- ULID-shaped event id (``evt_<26 base32 chars>``). Stable for the lifetime of the event; safe to use as a client-side dedupe key alongside the polymorphic ``object`` discriminator. object: type: string title: Object description: >- Always ``event``. The Stripe-style discriminator -- if a future API surface returns mixed object types in one envelope, partner handlers branch on this without having to parse the id prefix. type: type: string title: Type description: >- Event type, e.g. ``payment_intent.completed`` or ``address.deposit.received``. The full v1 vocabulary lives in CONNECT.md; unknown values from a forward-compat newer API version should be ignored, not failed. livemode: type: boolean title: Livemode description: >- True for events produced in the live environment (``sk_live_*`` key minted the intent / addresses), False for sandbox. Maps verbatim to the wire body's ``livemode`` field. Partner-side handlers should branch on this when downstream side-effects differ between modes (e.g. crediting a real merchant balance vs. a test one). related_to: anyOf: - type: string - type: 'null' title: Related To description: >- UUID (rendered as a string) of the principal object the event is about. Set for every event type we ship today; the column is nullable for forward-compat with future event types that have no natural principal (e.g. account-wide system notifications). related_to_kind: anyOf: - type: string - type: 'null' title: Related To Kind description: >- Names the table ``related_to`` resolves into. v1 vocabulary: ``payment_intent`` | ``address``. Always present iff ``related_to`` is. Future kinds (e.g. ``subscription``, ``payout``) will be added in lock-step with the corresponding event types. api_version: type: string title: Api Version description: >- Payload schema version. ``v1`` for the entire lifetime of this PR sequence. When the partner-visible payload shape changes incompatibly, this field bumps to ``v2`` and old events stay readable at their original version. created_at: type: string format: date-time title: Created At description: >- Server timestamp when the event row was written. The ULID id's timestamp prefix gives approximate creation-order sort, but ``created_at`` is the authoritative wall-clock value for filtering and display. data: additionalProperties: true type: object title: Data description: >- The business payload. Shape depends on ``type``: ``payment_intent.completed`` carries ``ref_code``, ``amount``, ``currency``, ``address_receiver``, ``address_sender``, ``network``, ``hash``, ``status``, ``metadata``; ``address.deposit.received`` (when shipped) carries the same set minus ``ref_code``. The full type-by-type payload reference lives in CONNECT.md. type: object required: - id - object - type - livemode - api_version - created_at - data title: ConnectEventLine description: |- A single event row in the partner-facing shape. Stripe-style envelope: every event carries ``object='event'`` so a polymorphic partner-side handler can dispatch on the discriminator. The ``data`` field is the business payload verbatim (the JSONB column on connect_events) -- no transformation between storage and wire shape. ``related_to`` and ``related_to_kind`` together identify the principal object the event is about. They move as a pair (both set or both null), enforced at the schema level by a CHECK constraint in the migration; partner-side handlers can safely use one to branch on the other. ConnectErrorBody: properties: type: type: string title: Type description: >- Stripe-style error category. One of: ``invalid_request_error``, ``authentication_error``, ``not_found_error``, ``rate_limit_error``, ``idempotency_error``, ``api_error``. Stable across minor versions; branch on this for top-level error routing. examples: - invalid_request_error code: type: string title: Code description: >- Machine-stable identifier for the specific failure. More specific than ``type``. Examples: ``invalid_request``, ``authentication_required``, ``expired_credential``, ``forbidden_scope``, ``account_pending_approval``, ``resource_not_found``, ``idempotency_conflict``, ``rate_limited``, ``internal_error``, ``not_yet_available``. Match on ``code`` in your client's error handler -- never parse ``message``. examples: - authentication_required message: type: string title: Message description: >- Human-readable explanation. Safe to surface in your own UI but may be reworded between releases -- never branch on the string. examples: - >- Missing or malformed Authorization header. Send: Authorization: Bearer sk_live_... or sk_test_... doc_url: type: string title: Doc Url description: >- Link to docs explaining this ``code``. Constructed as ``https://docs.zopay.cash/errors/``. Surface this in support tickets so we can investigate without a round-trip. examples: - https://docs.zopay.cash/errors/authentication_required param: anyOf: - type: string - type: 'null' title: Param description: >- Names the offending input field when the error is input-shape-related (mostly ``invalid_request_error`` from 400 and 422). Absent on auth, scope, rate-limit, and internal errors. examples: - currencies type: object required: - type - code - message - doc_url title: ConnectErrorBody description: |- The ``error`` object inside every /connect/v1 failure response. Mirrors ``ConnectError.to_envelope()`` in ``app/api/connect/errors.py``. Field set is locked -- adding a new field is a partner-visible contract change and requires a coordinated docs + schema update. securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: Connect API key (sk_live_… or sk_test_…) description: >- Paste your Connect API key (sk_live_… for production, sk_test_… for sandbox) without the ``Bearer `` prefix. Mint and rotate keys from the admin panel. ````