# Gas Station reference

Use this page to understand the main deployment settings and runtime interfaces for the Gas Station Service. The example shows one possible configuration shape; your release package, database, secrets, and telemetry pipeline can differ.

This page applies to on-premise deployments only. Ripple manages the Gas Station Service for SaaS.

## What this config controls

Gas Station is a background service that funds transaction fees for sponsored accounts on supported ledgers. It connects to the Ripple Custody API gateway, uses a bot-user private key for automated funding intents, stores processing state in PostgreSQL, and exports telemetry when configured.

## Configuration fields

Configure the service through environment variables or deployment values, depending on how your release packages Gas Station.

| Parameter | Description | Default | Required |
|  --- | --- | --- | --- |
| `GATEWAY_SERVER_URL` | Ripple Custody API gateway URL. | - | Yes |
| `PRIVATE_KEY` | Bot-user private key in PEM format. | - | Yes |
| `POLLING_INTERVAL_MS` | Interval for checking pending transactions, in milliseconds. | `5000` | No |
| `MAX_RETRY_ATTEMPTS` | Maximum immediate retry attempts for failed funding. | `3` | No |
| `RETRY_INTERVAL_MINUTES` | Interval between queued retry attempts. | `5` | No |
| `FEE_SAFETY_MARGIN_PERCENT` | Safety margin added to estimated fees. | `10` | No |
| `POSTGRES_URL` | PostgreSQL connection string. | - | Yes |
| `LOG_LEVEL` | Logging verbosity. Possible values: `debug`, `info`, `warn`, `error`. | `info` | No |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | OpenTelemetry collector endpoint. | - | No |


## Deployment values

The following fields show a possible values-file shape for the Gas Station Service:

| Field | Description |
|  --- | --- |
| `gasStation.enabled` | Turns on the Gas Station Service when the release package supports it. |
| `gasStation.gatewayUrl` | Ripple Custody API gateway URL. |
| `gasStation.pollingIntervalMs` | Polling interval in milliseconds. |
| `gasStation.maxRetryAttempts` | Maximum immediate retry attempts. |
| `gasStation.retryIntervalMinutes` | Queue retry interval in minutes. |
| `gasStation.feeSafetyMarginPercent` | Fee safety margin percentage. |
| `gasStation.database.*` | Database host, port, database name, username, and secret reference. |
| `gasStation.credentials.*` | Secret reference and key name for the bot user's private key. |
| `gasStation.telemetry.*` | Telemetry enablement and OTLP endpoint. |


If your release exposes Gas Station through component selection, include `gas-station` in `harmonize.included_components`.

## Database reference

Gas Station uses PostgreSQL for event deduplication, retry tracking, sponsorship configuration, alert thresholds, and audit data.

| Table | Purpose |
|  --- | --- |
| `processed_event` | Event deduplication and distributed locking. |
| `failed_funding_job` | Failed funding attempts for queue-based retry. |
| `dead_letter_queue` | Permanently failed jobs requiring investigation. |
| `sponsor` | Sponsorship configuration. |
| `alert` | Low-balance alert thresholds. |
| `event` | Audit trail for configuration changes. |


If you are using the shared Ripple Custody PostgreSQL instance, the Gas Station Service creates its own schema (`gas_station`) within the shared database. The database user must have `CREATE SCHEMA` privileges. See [PostgreSQL configuration](/products/custody/v1.36/deployment/reference/postgresql) for details on schema isolation across components.

## Health endpoints

| Endpoint | Purpose |
|  --- | --- |
| `/v1/health` | Liveness probe. |
| `/v1/ready` | Readiness probe. |


## Metrics and traces

Gas Station exports metrics and traces through OpenTelemetry when you configure telemetry.

| Metric | Type | Description |
|  --- | --- | --- |
| `failed_jobs_queue_size` | Gauge | Number of jobs in the failed funding queue. |
| `processed_events_count` | Gauge | Number of processed event rows. |
| `sponsor_balance_<ticker>` | Gauge | Current balance of each sponsor account. |
| `funding_attempts_total{status, chain}` | Counter | Funding attempts by status and chain. |
| `events_processed_total{outcome}` | Counter | Events processed by outcome. |
| `retry_attempts_total{attempt}` | Counter | Retry attempts before success or failure. |
| `funding_duration_seconds` | Histogram | Time from event detection to funding completion. |
| `job_age_at_success_hours` | Histogram | Time jobs spend in the queue before success. |
| `api_latency_seconds{endpoint}` | Histogram | API latency by endpoint. |


## Constraints and relationships

- Store `PRIVATE_KEY` in a Kubernetes secret or external secret-management system.
- Point `POSTGRES_URL` to a PostgreSQL database or schema that the service can access.
- Ensure `GATEWAY_SERVER_URL` resolves from the Gas Station runtime environment.
- Configure telemetry fields only when your deployment has an OpenTelemetry collector.
- Configure bot-user policies narrowly enough for Gas Station funding operations.


## Example

This example shows one possible Gas Station configuration shape:


```yaml
harmonize:
  included_components:
    - gas-station

gasStation:
  enabled: true
  gatewayUrl: "https://gateway.example.com"
  pollingIntervalMs: 5000
  maxRetryAttempts: 3
  retryIntervalMinutes: 5
  feeSafetyMarginPercent: 10

  database:
    host: "postgres.example.com"
    port: 5432
    name: "gas_station"
    username: "gas_station_user"
    existingSecret: "gas-station-db-credentials"

  credentials:
    existingSecret: "gas-station-credentials"
    privateKeyKey: "private-key"

  telemetry:
    enabled: true
    otlpEndpoint: "http://otel-collector:4317"
```

## Related topics

- [Gas Station](/products/custody/v1.36/accounts-and-assets/gas-station/overview)
- [Configure gas sponsorship](/products/custody/v1.36/accounts-and-assets/gas-station/configure-sponsorship)
- [Configure bot users](/products/custody/v1.36/governance/users/manage-users-and-roles#configure-a-bot-user-with-the-api)
- [Telemetry configuration](/products/custody/v1.36/deployment/reference/telemetry-configuration)
- [PostgreSQL configuration](/products/custody/v1.36/deployment/reference/postgresql)