List events

GET/v1/events

API key requiredCursor pagination

Events of the project for the key’s environment (user.*, kyc.*, transaction.*, withdrawal.*), newest first. Same identifiers as webhook deliveries.

Authentication#

Send a secret API key as Authorization: Bearer <key>. Both tp_test_… and tp_live_… keys work; the key decides which environment you read and write. See Authentication.

Parameters#

Query

Query parameters
Name	Type	Description
`limit`	integer	Number of items per page (1 to 100).Default 20
`starting_after`	string	Cursor: `id` of the last item of the previous page.
`type`	string	Filter on the type.One of`user.createduser.suspendeduser.unsuspendedkyc.approvedkyc.rejectedtransaction.receivedtransaction.completedwithdrawal.completedwithdrawal.failed`

See Pagination for how to walk through pages.

Responses#

200Page of events.

Headers

X-Request-Id Request identifier.
X-RateLimit-Limit Quota of the current window.
X-RateLimit-Remaining Requests remaining in the window.
X-RateLimit-Reset Seconds before the quota renews.

Body

objectstringrequired
always "list"
Example "list"
dataarray of Eventrequired
- idstringrequired
  Identifier, prefixed with evt_.
  pattern: ^evt_[0-9a-f-]{36}$
  Example "evt_0b2c8f6e-41f9-4c0a-8d55-6f6a3c1d9e21"
- objectstringrequired
  always "event"
  Example "event"
- typestringrequired
  Event type.
  One ofuser.createduser.suspendeduser.unsuspendedkyc.approvedkyc.rejectedtransaction.receivedtransaction.completedwithdrawal.completedwithdrawal.failed
  Example "user.created"
- created_atstringrequired
  Event date.
  format: date-time
  Example "2026-10-08T09:30:00.000Z"
- livemodebooleanrequired
  true for a live key, false for a sandbox key.
  Example false
- dataobjectrequired
  Content.
  - objectone of User | Kyc | Transactionrequired
    Snapshot of the resource concerned, at the time of the event: a user for user.*, a kyc for kyc.*, a transaction for transaction.* and withdrawal.*. Discriminate on its object field.
    VariantUser
    End user attached to your project.
    idstringrequired
    Opaque identifier.
    Example "4821"
    objectstringrequired
    always "user"
    Example "user"
    phonestringrequired
    Phone number in E.164 format.
    Example "+33612345678"
    external_idstring | nullrequired
    Your own identifier for this user.
    Example "cust_8f2a"
    verifiedbooleanrequired
    The phone number has been verified.
    Example true
    kyc_statusstringrequired
    Identity verification (KYC) status.
    One ofnonependingapprovedrejected
    Example "approved"
    suspendedbooleanrequired
    The user is suspended and can no longer transact.
    Example false
    livemodebooleanrequired
    true for a live key, false for a sandbox key.
    Example false
    wallet_statusstringrequired
    State of the user’s wallet. ready: the wallet exists. pending: its creation is in progress or being retried (never blocks the user; poll GET /v1/users/{id}/wallets). failed: creation was abandoned after repeated errors (contact support). none: no wallet is created at this step.
    One ofnonependingreadyfailed
    Example "ready"
    created_atstringrequired
    Creation date.
    format: date-time
    Example "2026-10-08T09:30:00.000Z"
    last_login_atstring | nullrequired
    Last sign-in.
    format: date-time
    Example "2026-10-08T09:30:00.000Z"
    VariantKyc
    Identity verification (KYC) status of a user.
    objectstringrequired
    always "kyc"
    Example "kyc"
    user_idstringrequired
    User concerned.
    Example "4821"
    statusstringrequired
    Status.
    One ofnonependingapprovedrejected
    Example "approved"
    livemodebooleanrequired
    true for a live key, false for a sandbox key.
    Example false
    VariantTransaction
    Movement of a user (deposit, withdrawal, payment, transfer).
    idstringrequired
    Opaque identifier.
    Example "90412"
    objectstringrequired
    always "transaction"
    Example "transaction"
    user_idstringrequired
    User concerned.
    Example "4821"
    typestringrequired
    Kind of movement.
    One ofdepositwithdrawalpaymenttransfer
    Example "deposit"
    directionstringrequired
    Direction, from the wallet’s point of view.
    One ofinout
    Example "in"
    amount_usdnumberrequired
    Amount in USDC (1 USDC = 1 USD).
    Example 100
    fee_usdnumber | nullrequired
    Fee applied (the project’s effective fees), when known.
    Example 0.6
    statusstringrequired
    Status.
    One ofpendingcompletedfailed
    Example "completed"
    fiat_currencystring | nullrequired
    Fiat currency (deposits and withdrawals).
    One ofEURUSD
    Example "USD"
    fiat_amountnumber | nullrequired
    Fiat amount.
    Example 100
    livemodebooleanrequired
    true for a live key, false for a sandbox key.
    Example false
    created_atstringrequired
    Creation date.
    format: date-time
    Example "2026-10-08T09:31:00.000Z"
has_morebooleanrequired
More items remain: call again with starting_after set to the id of the last item.
Example false

Example 200 response

{
  "object": "list",
  "data": [],
  "has_more": false
}

400Invalid request (malformed JSON, unknown cursor, invalid Idempotency-Key header).

Example: invalid_cursor

Example 400 response

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_cursor",
    "message": "starting_after: unknown cursor",
    "request_id": "0b2c8f6e-41f9-4c0a-8d55-6f6a3c1d9e21"
  }
}

401Missing, invalid or revoked API key.

Example: missing_api_key

Example 401 response

{
  "error": {
    "type": "authentication_error",
    "code": "missing_api_key",
    "message": "Provide your API key as \"Authorization: Bearer <key>\"",
    "request_id": "0b2c8f6e-41f9-4c0a-8d55-6f6a3c1d9e21"
  }
}

Example: invalid_api_key

Example 401 response

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The API key is invalid",
    "request_id": "0b2c8f6e-41f9-4c0a-8d55-6f6a3c1d9e21"
  }
}

Example: api_key_revoked

Example 401 response

{
  "error": {
    "type": "authentication_error",
    "code": "api_key_revoked",
    "message": "This API key has been revoked",
    "request_id": "0b2c8f6e-41f9-4c0a-8d55-6f6a3c1d9e21"
  }
}

403Organization suspended, live access not enabled, or sandbox-only route.

Example: organization_suspended

Example 403 response

{
  "error": {
    "type": "permission_error",
    "code": "organization_suspended",
    "message": "Your organization is suspended. Contact Tilt Pay support.",
    "request_id": "0b2c8f6e-41f9-4c0a-8d55-6f6a3c1d9e21"
  }
}

Example: live_not_enabled

Example 403 response

{
  "error": {
    "type": "permission_error",
    "code": "live_not_enabled",
    "message": "Live access has not been enabled for your organization yet",
    "request_id": "0b2c8f6e-41f9-4c0a-8d55-6f6a3c1d9e21"
  }
}

Example: sandbox_only

Example 403 response

{
  "error": {
    "type": "permission_error",
    "code": "sandbox_only",
    "message": "This route is only available with a sandbox API key",
    "request_id": "0b2c8f6e-41f9-4c0a-8d55-6f6a3c1d9e21"
  }
}

422Invalid parameter, or Idempotency-Key reused with a different body.

Example: validation_error

Example 422 response

{
  "error": {
    "type": "invalid_request_error",
    "code": "validation_error",
    "message": "phone: has an invalid format",
    "request_id": "0b2c8f6e-41f9-4c0a-8d55-6f6a3c1d9e21"
  }
}

Example: idempotency_key_reuse

Example 422 response

{
  "error": {
    "type": "idempotency_error",
    "code": "idempotency_key_reuse",
    "message": "This Idempotency-Key was already used with a different request",
    "request_id": "0b2c8f6e-41f9-4c0a-8d55-6f6a3c1d9e21"
  }
}

429Rate limit exceeded. Retry after the Retry-After delay (seconds).

Example: rate_limit_exceeded

Example 429 response

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Slow down and retry after the delay in Retry-After.",
    "request_id": "0b2c8f6e-41f9-4c0a-8d55-6f6a3c1d9e21"
  }
}

500Internal error. Retry; give request_id to support if it persists.

Example: internal_error

Example 500 response

{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "Internal server error",
    "request_id": "0b2c8f6e-41f9-4c0a-8d55-6f6a3c1d9e21"
  }
}

Headers on every response

X-Request-Id Identifier of the request, also present in error bodies. Give it to support.
X-API-Version Version of the API that answered.
X-RateLimit-Limit / -Remaining / -Reset Quota of your key for the current window. See Rate limits.

Errors#

Errors share one format, described in Errors. Branch your code on error.code.

Errors this route can return
Status	Code	Meaning
400	`invalid_cursor`	Unknown `starting_after` cursor.
401	`missing_api_key`	Missing, invalid or revoked API key.
401	`invalid_api_key`	Missing, invalid or revoked API key.
401	`api_key_revoked`	Missing, invalid or revoked API key.
403	`organization_suspended`	Organization suspended, live access not enabled, or sandbox-only route.
403	`live_not_enabled`	Organization suspended, live access not enabled, or sandbox-only route.
403	`sandbox_only`	Organization suspended, live access not enabled, or sandbox-only route.
422	`validation_error`	Invalid parameter, or `Idempotency-Key` reused with a different body.
422	`idempotency_key_reuse`	Invalid parameter, or `Idempotency-Key` reused with a different body.
429	`rate_limit_exceeded`	Rate limit exceeded. Retry after the `Retry-After` delay (seconds).
500	`internal_error`	Internal error. Retry; give `request_id` to support if it persists.

Code examples#

curl "https://sdk.tilt-pay.com/v1/events?limit=20" \
  -H "Authorization: Bearer $TILT_PAY_API_KEY"

Try it#

Sends a real request to the API with a sandbox key. No real data is touched.

Sandbox key

The playground sends real requests to the API with a sandbox key. Live keys are refused.

limit (query)

starting_after (query)

type (query)

Request

Exactly what is sent (key masked)

GET https://api-hub.tilt-pay.com/v1/events?limit=5
Accept: application/json
Authorization: Bearer <your sandbox key>

Add a sandbox key to send.