# 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, authenticates as a service caller registered in Keycloak, submits automated funding intents as system-signed intents, stores processing state in PostgreSQL, and exports telemetry when configured.

Migration from bot users
Earlier releases used a bot-user private key for automated funding intents. Gas Station now uses system-signed intents instead. Existing deployments must migrate before they upgrade, or automated funding stops. See [Migrate from a bot user](#migrate-from-a-bot-user).

## Migrate from a bot user

If you funded Gas Station with a bot-user private key in an earlier release, migrate to system-signed intents in this order so that funding does not stop:

1. Activate system-signed intents for the deployment. See [System-signed intent configuration](/products/custody/v1.38/deployment/reference/system-signed-intents).
2. Register the Gas Station service caller in Keycloak and issue it a `custody_roles` claim. See [Obtain a token for a service caller](/products/custody/v1.38/identity-and-access/authentication/authenticate-api-requests#obtain-a-token-for-a-service-caller).
3. Create a policy with `intentOrigin: "SystemSigned"` that allows the service caller to submit `v0_CreateTransactionOrder`. See [System-signed intents and policies](/products/custody/v1.38/accounts-and-assets/gas-station/overview#system-signed-intents-and-policies).
4. Redeploy Gas Station with the service-caller credentials. Remove the `PRIVATE_KEY` environment variable and the `gasStation.credentials.privateKeyKey` value.
5. Confirm that new funding intents execute, then decommission the bot user.


## Configuration fields

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

The `HMZ_FEATURE_GAS_STATION` deployment flag controls whether the console displays the Gas station pages, including [gas station creation](/products/custody/v1.38/accounts-and-assets/gas-station/manage-gas-station-ui#create-a-gas-station).

| Parameter | Description | Default | Required |
|  --- | --- | --- | --- |
| `GATEWAY_SERVER_URL` | Ripple Custody API gateway URL. | - | Yes |
| Service-caller credentials | Client credentials for the Gas Station service caller registered in Keycloak. The exact parameters depend on your release package; contact your Customer Partner Engineer (CPE) for the specifics. | - | 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 for the Gas Station service-caller (Keycloak client) credentials. |
| `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.38/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 the service-caller credentials 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.
- Scope the Gas Station system-signed policy narrowly enough for 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"

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

## Related topics

- [Gas Station](/products/custody/v1.38/accounts-and-assets/gas-station/overview)
- [Manage a gas station with the API](/products/custody/v1.38/accounts-and-assets/gas-station/manage-gas-station-api)
- [System-signed intent configuration](/products/custody/v1.38/deployment/reference/system-signed-intents)
- [Telemetry configuration](/products/custody/v1.38/deployment/reference/telemetry-configuration)
- [PostgreSQL configuration](/products/custody/v1.38/deployment/reference/postgresql)