# Manage a gas station with the API

Use this page for gas station operations with the API. For console procedures, see [Manage a gas station in the UI](/products/custody/accounts-and-assets/gas-station/manage-gas-station-ui). For the sponsorship model, see [Gas Station](/products/custody/accounts-and-assets/gas-station/overview).

All examples use the base URL `${CUSTODY_API_URL}/v1`, where `CUSTODY_API_URL` is your Ripple Custody API gateway URL.

Terminology
| Term | Description |
|  --- | --- |
| Gas station | Account configured to sponsor transaction fees. |
| Sponsor account | Same as gas station; the account that provides native tokens for fees. |
| Sponsored account | Account that can receive fee funding from a sponsor account. |
| `accountId` | In `/account/{accountId}/sponsor`, the sponsor account. |
| `entityId` | In `/account/{entityId}/sponsorable-*` and `/sponsored-*`, the sponsor account. |


## Gas station actions

| Action | API procedure |
|  --- | --- |
| Create a gas station | [Create a gas station](#create-a-gas-station) |
| Check balances | [Check gas station balances](#check-gas-station-balances) |
| Fund the gas station | [Fund the gas station](#fund-the-gas-station) |
| Release quarantined funding | [Release quarantined transfers](#release-quarantined-transfers) |
| Create sponsorship | [Create sponsorship](#create-sponsorship) |
| View, update, or delete sponsorship | [View sponsorship](#view-sponsorship), [Update sponsorship](#update-sponsorship), [Delete sponsorship](#delete-sponsorship) |
| Set low-balance alerts | [Configure alert thresholds](#configure-alert-thresholds) |
| View sponsorship audit events | [View audit events](#view-audit-events) |
| Manage sponsored accounts and domains | [Manage sponsored accounts](#manage-sponsored-accounts), [Manage sponsored domains](#manage-sponsored-domains) |
| List sponsors and sponsored entities | [List sponsor accounts and sponsored entities](#list-sponsor-accounts-and-sponsored-entities) |


## Create a gas station

A gas station is a regular custody account that holds native tokens and has a sponsor configuration:

1. Create the account with a `v0_CreateAccount` intent, selecting the ledgers the gas station sponsors. See [Create an account with the API](/products/custody/accounts-and-assets/accounts/manage-accounts-api).
2. After the intent executes, create the account's sponsor configuration. See [Create sponsorship](#create-sponsorship).


## Check gas station balances

Gas station balances are regular account balances. Use [Get account balances](/products/custody/reference/api/openapi/accounts/getaccountbalances) and read the `availableAmount` field per ledger.

## Fund the gas station

Fund the gas station with a standard transfer to its account on the target ledger. See [Send assets with the API](/products/custody/transactions/send-and-receive/send-assets-api).

## Release quarantined transfers

If transaction screening quarantines incoming funding, the gas station can't spend it. Release the held transfers with a `v0_ReleaseQuarantinedTransfers` intent, or configure an [automatic quarantine release policy](/products/custody/compliance/transaction-screening/automatic-quarantine-release-policy). See [Receive assets with the API](/products/custody/transactions/send-and-receive/receive-assets-api).

## Prerequisites

Before configuring sponsorship, confirm that:

- Your environment has Gas Station deployed or available.
- System-signed intents are activated, the Gas Station service caller is registered in Keycloak, and a Gas Station system-signed policy is in place. See [System-signed intents and policies](/products/custody/accounts-and-assets/gas-station/overview#system-signed-intents-and-policies).
- The sponsor account has the native tokens required by the target ledger.
- You have a valid API token. See [Authenticate API requests](/products/custody/identity-and-access/authentication/authenticate-api-requests).


## API reference

For the complete schema, parameters, and response details, see [Gas station](/products/custody/reference/api/openapi/gas-station) in the API reference.

## Create sponsorship

Create a sponsorship configuration for a sponsor account with `POST /v1/domains/{domainId}/account/{accountId}/sponsor`.

### Account-level sponsorship

Use `type: "account"` to sponsor specific accounts.

```bash
curl -X POST "${CUSTODY_API_URL}/v1/domains/{domainId}/account/{accountId}/sponsor" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "account",
    "accountIds": ["account-uuid-1", "account-uuid-2"],
    "includeSubDomains": false,
    "alertLimit": [
      {
        "tickerId": "native-token-ticker-uuid",
        "amount": "1.0"
      }
    ]
  }'
```

### Domain-level sponsorship

Use `type: "domain"` to sponsor accounts in the domain. Set `includeSubDomains` to `true` if sponsorship should include child domains.

```bash
curl -X POST "${CUSTODY_API_URL}/v1/domains/{domainId}/account/{accountId}/sponsor" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "domain",
    "includeSubDomains": true,
    "alertLimit": [
      {
        "tickerId": "native-token-ticker-uuid",
        "amount": "5.0"
      }
    ]
  }'
```

### Request fields

| Field | Type | Required | Description |
|  --- | --- | --- | --- |
| `type` | string | Yes | Sponsorship type: `account`, `domain`, or `none`. |
| `accountIds` | array | No | Account UUIDs to sponsor when `type` is `account`. |
| `includeSubDomains` | boolean | Yes | Whether domain sponsorship includes subdomains. |
| `alertLimit` | array | Yes | Low-balance thresholds per ticker. |
| `userId` | string | No | User to record on the audit trail. Eligible automated callers can set this value; otherwise the API uses the authenticated user from the JWT. |


### Response

Successful create requests return `201 Created`.

```json
{
  "id": "sponsor-config-uuid",
  "status": "created",
  "createdAt": "2026-01-15T10:30:00Z"
}
```

## View sponsorship

Use `GET /v1/domains/{domainId}/account/{accountId}/sponsor` to retrieve the sponsor account's configuration.

```bash
curl -X GET "${CUSTODY_API_URL}/v1/domains/{domainId}/account/{accountId}/sponsor" \
  -H "Authorization: Bearer {token}"
```

If no sponsorship configuration exists for the sponsor account, this endpoint
returns `404`. This result can mean the account does not have a configuration yet. Use
`GET /v1/domains/{domainId}/sponsors` to list sponsor-capable accounts in the
domain.

Use `GET /v1/domains/{domainId}/sponsors/account/{accountId}/sponsor` to check sponsorship status for an account.

```bash
curl -X GET "${CUSTODY_API_URL}/v1/domains/{domainId}/sponsors/account/{accountId}/sponsor" \
  -H "Authorization: Bearer {token}"
```

Use `GET /v1/domains/{domainId}/sponsors/account/{accountId}/valid-sponsors` to list the gas stations that could sponsor a specific account: every sponsor in the account's domain or one of its ancestor domains, excluding the account itself.

```bash
curl -X GET "${CUSTODY_API_URL}/v1/domains/{domainId}/sponsors/account/{accountId}/valid-sponsors" \
  -H "Authorization: Bearer {token}"
```

An account is only sponsored once. If the account is already effectively sponsored, the response returns `isSponsored: true` with the existing sponsor and an empty `items` list. Set the `includeAll` query parameter to list the lineage's valid sponsor candidates anyway; the current sponsor can appear among them.

## Update sponsorship

Use `PUT /v1/domains/{domainId}/account/{accountId}/sponsor` to replace the sponsor account's sponsorship configuration.

```bash
curl -X PUT "${CUSTODY_API_URL}/v1/domains/{domainId}/account/{accountId}/sponsor" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "account",
    "accountIds": ["account-uuid-1"],
    "includeSubDomains": false,
    "alertLimit": [
      {
        "tickerId": "native-token-ticker-uuid",
        "amount": "2.0"
      }
    ]
  }'
```

To disable sponsorship without deleting the sponsor configuration, update the configuration with `type: "none"`.

Successful update requests return `200 OK`. A configuration with `type: "none"`
disables sponsorship and does not make the account an active sponsor for Omnibus.

## Delete sponsorship

Use `DELETE /v1/domains/{domainId}/account/{accountId}/sponsor` to delete a sponsor configuration. Include the `userId` query parameter.

```bash
curl -X DELETE "${CUSTODY_API_URL}/v1/domains/{domainId}/account/{accountId}/sponsor?userId={userId}" \
  -H "Authorization: Bearer {token}"
```

Successful delete requests return `204 No Content`.

After you delete or disable sponsorship, affected accounts need enough native token balance to pay their own transaction fees.

## Configure alert thresholds

Use `alertLimit` entries when creating or updating sponsorship to define native-token balance thresholds for the sponsor account.

```json
{
  "alertLimit": [
    {
      "tickerId": "native-token-ticker-uuid",
      "amount": "1.0"
    }
  ]
}
```

Monitor alert output through the telemetry and logging pipeline configured for your Gas Station deployment.

## View audit events

Use `GET /v1/domains/{domainId}/sponsor/events` to retrieve sponsorship audit events.

```bash
curl -X GET "${CUSTODY_API_URL}/v1/domains/{domainId}/sponsor/events?limit=100" \
  -H "Authorization: Bearer {token}"
```

| Query parameter | Description |
|  --- | --- |
| `accountId` | Filter events for a specific account. |
| `startDate` | Include events from this date. |
| `endDate` | Include events until this date. |
| `eventType` | Filter by `CREATE`, `UPDATE`, or `DELETE`. |
| `limit` | Maximum number of events to return. |
| `startingAfter` | Pagination cursor. |


## Manage sponsored accounts

Use `GET /v1/domains/{domainId}/account/{entityId}/sponsorable-accounts` to view accounts eligible for a sponsor account's sponsorship.

```bash
curl -X GET "${CUSTODY_API_URL}/v1/domains/{domainId}/account/{entityId}/sponsorable-accounts?page=0&limit=20" \
  -H "Authorization: Bearer {token}"
```

| Query parameter | Description |
|  --- | --- |
| `status` | Filter by `sponsored`, `not_sponsored`, or `sponsored_by_other`. |
| `search` | Search accounts. |
| `limit` | Number of results per page. |
| `page` | Page number, starting at `0`. |


Example response:

```json
{
  "items": [
    {
      "accountId": "account-uuid",
      "name": "Trading Account",
      "lineage": {
        "domainId": "parent-domain-uuid",
        "domain": "Parent Domain",
        "subdomainId": "subdomain-uuid",
        "subdomain": "Sub Domain"
      },
      "ledgers": [
        {
          "id": "ledger-uuid",
          "alias": "Ethereum"
        }
      ],
      "sponsorshipStatus": "not_sponsored"
    }
  ],
  "total": 1,
  "page": 0,
  "pageSize": 20,
  "availableLedgers": [
    {
      "id": "ledger-uuid",
      "alias": "Ethereum"
    }
  ]
}
```

Use `POST /v1/domains/{domainId}/account/{entityId}/sponsored-accounts` to add accounts to a sponsor account's sponsorship.

```bash
curl -X POST "${CUSTODY_API_URL}/v1/domains/{domainId}/account/{entityId}/sponsored-accounts" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "accounts": [
      {
        "accountId": "account-uuid-1",
        "domainId": "domain-uuid-1"
      }
    ]
  }'
```

Each add-sponsored-accounts request accepts up to 100 accounts. Successful requests return `201 Created`.

The response contains `success`, `count`, and, when applicable, `conflicts`.
Use the optional `userId` request field when you need to record a specific user
on the audit trail.

To add or remove one sponsored account, use the single-account endpoints instead of the bulk operation:

- `PUT /v1/domains/{domainId}/account/{entityId}/sponsored-accounts/domains/{sponsoredAccountDomainId}/accounts/{sponsoredAccountId}` adds a single sponsored account. The operation is idempotent: it returns `201 Created` when it adds the account and `204 No Content` when the sponsor already sponsors the account. It returns `409` when another sponsor already sponsors the account.
- `DELETE /v1/domains/{domainId}/account/{entityId}/sponsored-accounts/domains/{sponsoredAccountDomainId}/accounts/{sponsoredAccountId}` removes a single sponsored account and returns `204 No Content`.


```bash
curl -X PUT "${CUSTODY_API_URL}/v1/domains/{domainId}/account/{entityId}/sponsored-accounts/domains/{sponsoredAccountDomainId}/accounts/{sponsoredAccountId}" \
  -H "Authorization: Bearer {token}"
```

## Manage sponsored domains

Use `GET /v1/domains/{domainId}/account/{entityId}/sponsorable-domains` to view domains eligible for a sponsor account's sponsorship.

```bash
curl -X GET "${CUSTODY_API_URL}/v1/domains/{domainId}/account/{entityId}/sponsorable-domains?page=0&limit=20" \
  -H "Authorization: Bearer {token}"
```

| Query parameter | Description |
|  --- | --- |
| `status` | Filter by `sponsored`, `not_sponsored`, or `sponsored_by_other`. |
| `search` | Search domains. |
| `limit` | Number of results per page. |
| `page` | Page number, starting at `0`. |


Use `POST /v1/domains/{domainId}/account/{entityId}/sponsored-domains` to add domains to a sponsor account's sponsorship.

```bash
curl -X POST "${CUSTODY_API_URL}/v1/domains/{domainId}/account/{entityId}/sponsored-domains" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "domains": [
      {
        "domainId": "domain-uuid-1"
      }
    ]
  }'
```

Each add-sponsored-domains request accepts up to 100 domains. Successful requests return `201 Created`.

The response contains `success`, `count`, and, when applicable, `conflicts`.
Use the optional `userId` request field when you need to record a specific user
on the audit trail.

## List sponsor accounts and sponsored entities

Use `GET /v1/domains/{domainId}/sponsors` to list sponsor accounts in a domain.

```bash
curl -X GET "${CUSTODY_API_URL}/v1/domains/{domainId}/sponsors" \
  -H "Authorization: Bearer {token}"
```

The response contains an `items` array of sponsor account IDs.

Use `GET /v1/domains/{domainId}/sponsors/sponsored-accounts` to list accounts with sponsorship status.

```bash
curl -X GET "${CUSTODY_API_URL}/v1/domains/{domainId}/sponsors/sponsored-accounts?limit=50&sortBy=alias&sortOrder=asc" \
  -H "Authorization: Bearer {token}"
```

Use `GET /v1/domains/{domainId}/sponsors/sponsored-domains` to list subdomains with sponsorship status.

```bash
curl -X GET "${CUSTODY_API_URL}/v1/domains/{domainId}/sponsors/sponsored-domains?limit=50&sortBy=alias&sortOrder=asc" \
  -H "Authorization: Bearer {token}"
```

These list endpoints support `limit`, `startingAfter`, `sortBy`, `sortOrder`, and `sponsorAccountId` query parameters.

## Troubleshooting

| Symptom | Possible cause |
|  --- | --- |
| Transaction waits for funding | No sponsorship applies to the account or its domain. |
| Transaction waits for funding | Sponsor account has insufficient native token balance. |
| Funding intent waits for approval | The policy matching Gas Station's system-signed funding intents requires approvals. |
| Funding intents are rejected | System-signed intents are not activated, or no policy with `intentOrigin: "SystemSigned"` allows the Gas Station service caller. |
| Funding activity is not visible | Check Gas Station service health, logs, and telemetry. |


## Related topics

| Topic | Documentation |
|  --- | --- |
| Gas Station concepts | [Gas Station](/products/custody/accounts-and-assets/gas-station/overview) |
| UI procedures | [Manage a gas station in the UI](/products/custody/accounts-and-assets/gas-station/manage-gas-station-ui) |
| Deployment reference | [Gas Station reference](/products/custody/deployment/reference/gas-station) |
| System-signed intents | [System-signed intent configuration](/products/custody/deployment/reference/system-signed-intents) |