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. For the sponsorship model, see Gas Station.

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
Check balances	Check gas station balances
Fund the gas station	Fund the gas station
Release quarantined funding	Release quarantined transfers
Create sponsorship	Create sponsorship
View, update, or delete sponsorship	View sponsorship, Update sponsorship, Delete sponsorship
Set low-balance alerts	Configure alert thresholds
View sponsorship audit events	View audit events
Manage sponsored accounts and domains	Manage sponsored accounts, Manage sponsored domains
List sponsors 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:

Create the account with a v0_CreateAccount intent, selecting the ledgers the gas station sponsors. See Create an account with the API.
After the intent executes, create the account's sponsor configuration. See Create sponsorship.

Check gas station balances

Gas station balances are regular account balances. Use Get account balances 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.

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. See Receive assets with the 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.
The sponsor account has the native tokens required by the target ledger.
You have a valid API token. See Authenticate API requests.

API reference

For the complete schema, parameters, and response details, see 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.

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.

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.

{
  "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.

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.

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.

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.

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.

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.

{
  "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.

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.

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:

{
  "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.

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.

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.

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.

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.