# Configure gas sponsorship

Use Gas Station sponsorship APIs to define which accounts or domains receive automatic native-token funding for supported transaction fees.

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

Path format
Gas Station endpoint paths use `domain` as the singular segment before
`{domainId}`. Core Ripple Custody and Omnibus endpoint paths use the
plural segment `domains`.

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


## Prerequisites

Before configuring sponsorship, confirm that:

- Your environment has Gas Station deployed or available.
- You configured a [bot user](/products/custody/governance/users/manage-users-and-roles#configure-a-bot-user-with-the-api) for automated funding.
- 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/domain/{domainId}/account/{accountId}/sponsor`.

### Account-level sponsorship

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


```bash
curl -X POST "${CUSTODY_API_URL}/v1/domain/{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/domain/{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/domain/{domainId}/account/{accountId}/sponsor` to retrieve the sponsor account's configuration.


```bash
curl -X GET "${CUSTODY_API_URL}/v1/domain/{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/domain/{domainId}/sponsors` to list sponsor-capable accounts in the
domain.

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


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

## Update sponsorship

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


```bash
curl -X PUT "${CUSTODY_API_URL}/v1/domain/{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/domain/{domainId}/account/{accountId}/sponsor` to delete a sponsor configuration. Include the `userId` query parameter.


```bash
curl -X DELETE "${CUSTODY_API_URL}/v1/domain/{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/domain/{domainId}/sponsor/events` to retrieve sponsorship audit events.


```bash
curl -X GET "${CUSTODY_API_URL}/v1/domain/{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/domain/{domainId}/account/{entityId}/sponsorable-accounts` to view accounts eligible for a sponsor account's sponsorship.


```bash
curl -X GET "${CUSTODY_API_URL}/v1/domain/{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/domain/{domainId}/account/{entityId}/sponsored-accounts` to add accounts to a sponsor account's sponsorship.


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

Successful add-sponsored-accounts 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.

## Manage sponsored domains

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


```bash
curl -X GET "${CUSTODY_API_URL}/v1/domain/{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/domain/{domainId}/account/{entityId}/sponsored-domains` to add domains to a sponsor account's sponsorship.


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

Successful add-sponsored-domains 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/domain/{domainId}/sponsors` to list sponsor accounts in a domain.


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

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

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


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

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


```bash
curl -X GET "${CUSTODY_API_URL}/v1/domain/{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 | Bot-user policies require approvals for funding. |
| 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) |
| Deployment reference | [Gas Station reference](/products/custody/deployment/reference/gas-station) |
| Bot users | [Configure bot users](/products/custody/governance/users/manage-users-and-roles#configure-a-bot-user-with-the-api) |