> For the complete documentation index, see [llms.txt](https://docs.blinklabs.xyz/blink/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.blinklabs.xyz/blink/robinhood-chain/gas-sponsorship/api-reference.md).

# API Reference

Gas sponsorship is enabled per API key. Once your key is enabled, sponsored transactions use your existing Robinhood Chain endpoint at `https://robinhood.blinklabs.xyz/v1/<API_KEY>`, with one addition: `eth_sendRawTransaction` must carry the `sponsorship=true` query string parameter, exactly as it does on Ethereum.

{% stepper %}
{% step %}

## Ask whether the transaction is sponsorable

Send the unsigned transaction to `pm_isSponsorable`.
{% endstep %}

{% step %}

## Sign it with a normal gas price

Bypass your local balance and simulation checks — they will fail, and that is expected.
{% endstep %}

{% step %}

## Submit it with `eth_sendRawTransaction`

Append the `sponsorship=true` query parameter, and send it to Blink only.
{% endstep %}
{% endstepper %}

### Checking for Transaction Sponsorship <a href="#checking-for-transaction-sponsorship" id="checking-for-transaction-sponsorship"></a>

To check whether a swap is sponsorable, first send your unsigned transaction to your RPC endpoint at `https://robinhood.blinklabs.xyz/v1/<API_KEY>` with the following POST request

#### pm\_isSponsorable

{% code overflow="wrap" %}

```json
{
    "jsonrpc": "2.0",
    "method": "pm_isSponsorable",
    "params": [
        {
          "to": "<TX_TO_ADDRESS>",
          "from": "<TX_FROM_ADDRESS>",
          "value": "<TX_VALUE_HEX>",
          "data": "<TX_DATA_HEX>",
          "gas": "<TX_GAS_LIMIT_HEX>"
        }
    ],
    "id": 1
}
```

{% endcode %}

Example request — an ERC-20 approval granting one of your whitelisted routers an allowance. The token and spender addresses below are placeholders:

{% code overflow="wrap" %}

```json
{
    "jsonrpc": "2.0",
    "method": "pm_isSponsorable",
    "params": [
        {
          "to": "0x2222222222222222222222222222222222222222",
          "from": "0x1234567890b4fa4756b8db7a52e4150e6c18fc2c",
          "value": "0x0",
          "data": "0x095ea7b30000000000000000000000001111111111111111111111111111111111111111ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
          "gas": "0xfde8"
        }
    ],
    "id": 0
}
```

{% endcode %}

For a swap, `to` is the swap contract itself and must be one of the contracts on your whitelist. For an approval, `to` is the token and the spender encoded in `data` must be one of your whitelisted routers.

Example response:

{% code overflow="wrap" %}

```json
{
    "id": 0,
    "result": {
        "sponsorable": true,
        "sponsorName": "Blink",
        "sponsorIcon": "https://framerusercontent.com/images/o61GQaQ3nRGkpdVnUD5P3HhDxx0.png",
        "sponsorWebsite": "https://blinklabs.xyz/"
    },
    "jsonrpc": "2.0"
}
```

{% endcode %}

If `sponsorable` returns `true`, your transaction is sponsorable.

If the transaction is not sponsorable, the response returns `false` with a `reason` explaining why:

{% code overflow="wrap" %}

```json
{
    "id": 0,
    "result": {
        "sponsorable": false,
        "sponsorName": "Blink",
        "sponsorIcon": "https://framerusercontent.com/images/o61GQaQ3nRGkpdVnUD5P3HhDxx0.png",
        "sponsorWebsite": "https://blinklabs.xyz/",
        "reason": "max swaps per day exceeded"
    },
    "jsonrpc": "2.0"
}
```

{% endcode %}

The `reason` is a human-readable explanation, not a fixed set of values. Log or display it rather than matching on its text.

### Signing a Sponsored Transaction

Two things are different from an ordinary Robinhood Chain transaction, and both follow from the account being unfunded at the moment you sign.

#### Set a normal gas price

Sign with a real, non-zero gas price, exactly as you would an unsponsored transaction. Blink sizes the funding transfer to cover it.

{% hint style="danger" %}
Do not carry a zero gas price over from a BSC integration. On BSC, sponsored transactions are signed with a gas price of `0` and Blink pays the validator directly. Robinhood Chain has a base fee, and a transaction priced at zero will not be included.
{% endhint %}

#### Expect your own checks to fail

The account genuinely cannot afford the transaction yet. Any balance check, local simulation, or `eth_estimateGas` run against current state will report insufficient funds. Submit anyway — `pm_isSponsorable` returning `true` is the check that matters on this path.

{% hint style="warning" %}
Keep the gas limit tight. A sponsored transaction is funded for the full gas limit it is signed with, not for what it uses, and the difference stays with the user. See [Gas Limits and What Sponsorship Costs You](/blink/robinhood-chain/gas-sponsorship.md#gas-limits-and-what-sponsorship-costs-you).
{% endhint %}

### Submitting the Transaction

#### eth\_sendRawTransaction

Submit the signed transaction as you normally would, with one difference: you must add the query string parameter `sponsorship=true`. This matches Ethereum. The full URL is:

`https://robinhood.blinklabs.xyz/v1/<API_KEY>?sponsorship=true`

{% hint style="danger" %}
Without `sponsorship=true` the transaction is submitted as an ordinary, unsponsored transaction. No funding transfer is sent, and an account that cannot cover its own gas will simply fail. This is the easiest mistake to make in the whole integration — `pm_isSponsorable` returning `true` does not sponsor anything on its own.
{% endhint %}

{% code overflow="wrap" %}

```json
{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "eth_sendRawTransaction",
    "params": [
        "0x..."
     ]
}
```

{% endcode %}

Example response:

{% code overflow="wrap" %}

```json
{
    "id": 1,
    "jsonrpc": "2.0",
    "result": "0x..."
}
```

{% endcode %}

The hash returned is the user's own transaction hash. The funding transfer is a separate transaction from a Blink sponsor address and is not returned here.

{% hint style="danger" %}
Send the signed transaction to Blink only. Do not broadcast it to another RPC endpoint in parallel. On Robinhood Chain the funding transfer and the user's transaction are independent transactions ordered by arrival, so a copy that reaches the sequencer by another route can arrive ahead of its own funding and be rejected for insufficient funds.
{% endhint %}

### Notes

* Pass the same transaction data to `eth_sendRawTransaction` that you passed to `pm_isSponsorable`. If it differs, the transaction may no longer qualify.
* By default we only sponsor when the account cannot cover the transaction itself. Sponsoring accounts that already hold a balance is available on request.
* Transactions that are not sponsorable are handled exactly as they are today — `pm_isSponsorable` returning `false` simply tells you the user needs to cover their own gas.
* Sponsorable criteria are configured per API key: whitelisted swap contracts and approval spenders, per-user daily caps, gas limit ceilings, and whether per-transaction profitability is enforced. See [Gas Sponsorship](/blink/robinhood-chain/gas-sponsorship.md) to set yours up.