# API keys

> Request and manage your Supanode SWQoS API key through Telegram; HTTP and QUIC authentication.

<span id="swqos-keys" />

## Request and manage your key

Contact [Supanode on Telegram](https://telegram.me/supanode_tgs). We issue your SWQoS key and confirm its minimum tip, send rate and enabled features. Request additional keys, rotation, pause, resumption or revocation through the same channel. You do not need a partner console account. Store the secret securely; do not expose it in browser code, repositories or support logs.

The default minimum tip is 1,000,000 lamports (0.001 SOL) and the default rate is 15 sends per second per key per metro. Your issued key can have different settings. SWQoS keys are separate from read RPC credentials. Support manages any account-management credentials; they are not used for transaction submissions.

<span id="declared-tips" />

## Access and billing

SWQoS tips are paid in SOL. There is no subscription or per-send fee. The default minimum on-chain tip is 0.001 SOL; the tip transfers only if execution succeeds. Network fees are separate.

Declared tips are off by default. Request enablement and agree payment with Supanode before using them. A declaration is billed under that arrangement; it is separate from an on-chain transfer and from other product subscriptions. An overdue declared-tip payment can suspend submissions while queries remain available. Adding an on-chain transfer does not bypass a payment suspension. See [declared-tip billing and retry rules](https://supanode.xyz/docs/solana/sender/tips#declared-tips).

Supanode handles keys, enabled features and payment questions through [Telegram](https://telegram.me/supanode_tgs). Ask for the applicable service terms there. Do not create or send account-management credentials to a transaction endpoint.

### HTTP

Send the key in the `x-api-key` header. This keeps it out of request URLs.
The [authentication reference](https://supanode.xyz/docs/solana/sender/reference/json-rpc#authentication) covers compatibility
forms and their precedence.

Set `SWQOS_API_KEY` to your key. These examples call `getHealth` to check the connection without submitting a transaction. Rust and Go use the
[example project](https://supanode.xyz/docs/solana/sender/reference/json-rpc#example-project); TypeScript uses `fetch`.

<Tabs>

<Tab title="Rust">

```rust title="src/bin/api_key_header.rs" tab="Rust" tab-group="language"
use serde_json::{Value, json};
use swqos_examples::swqos::{Result, required};

#[tokio::main]
async fn main() -> Result<()> {
    let response = reqwest::Client::new()
        .post("https://fra.tpu.supanode.xyz")
        .header("x-api-key", required("SWQOS_API_KEY")?)
        .json(&json!({ "jsonrpc": "2.0", "id": 1, "method": "getHealth" }))
        .send()
        .await?;
    let status = response.status();
    let body = response.text().await?;
    let reply: Value = serde_json::from_str(&body)
        .map_err(|error| format!("HTTP {status}: {error}; body: {body}"))?;
    if !status.is_success() || reply.get("error").is_some_and(|error| !error.is_null()) {
        return Err(format!("HTTP {status}: {reply}").into());
    }
    println!("{}", serde_json::to_string_pretty(&reply)?);
    Ok(())
}
```

</Tab>

<Tab title="Go">

```go title="api-key-header/main.go" tab="Go" tab-group="language"
package main

import (
	"encoding/json"
	"fmt"
	"log"
	"net/http"
	"strings"

	swqos "swqos-examples"
)

func main() {
	if err := run(); err != nil {
		log.Fatal(err)
	}
}

func run() error {
	apiKey, err := swqos.Required("SWQOS_API_KEY")
	if err != nil {
		return err
	}
	request, err := http.NewRequest(http.MethodPost, "https://fra.tpu.supanode.xyz",
		strings.NewReader(`{"jsonrpc":"2.0","id":1,"method":"getHealth"}`))
	if err != nil {
		return err
	}
	request.Header.Set("x-api-key", apiKey)
	request.Header.Set("Content-Type", "application/json")
	response, err := http.DefaultClient.Do(request)
	if err != nil {
		return err
	}
	defer response.Body.Close()
	var reply map[string]any
	if err := json.NewDecoder(response.Body).Decode(&reply); err != nil {
		return fmt.Errorf("HTTP %d: %w", response.StatusCode, err)
	}
	if response.StatusCode < 200 || response.StatusCode >= 300 || reply["error"] != nil {
		return fmt.Errorf("HTTP %d: %v", response.StatusCode, reply)
	}
	output, err := json.MarshalIndent(reply, "", "  ")
	if err != nil {
		return err
	}
	fmt.Println(string(output))
	return nil
}
```

</Tab>

<Tab title="TypeScript">

```ts title="api-key-header.ts" tab="TypeScript" tab-group="language"
const apiKey = process.env.SWQOS_API_KEY
if (!apiKey) throw new Error('set SWQOS_API_KEY')

const response = await fetch('https://fra.tpu.supanode.xyz', {
  method: 'POST',
  headers: { 'x-api-key': apiKey, 'content-type': 'application/json' },
  body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'getHealth' }),
})
const body = await response.text()
let reply: { error?: unknown }
try {
  reply = JSON.parse(body)
} catch {
  throw new Error(`HTTP ${response.status}: invalid JSON; body: ${body}`)
}
if (!response.ok || reply.error != null) {
  throw new Error(`HTTP ${response.status}: ${JSON.stringify(reply)}`)
}
console.log(JSON.stringify(reply, null, 2))

export {}
```

</Tab>

<Tab title="cURL">

```sh title="HTTP key header" tab="cURL" tab-group="language"
curl --fail-with-body -sS 'https://fra.tpu.supanode.xyz' \
  -H "x-api-key: $SWQOS_API_KEY" \
  -H 'content-type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"getHealth"}'
```

</Tab>

</Tabs>

All HTTP routes need a key except `GET /health`. Use HTTPS. Hosted endpoints do not
provide CORS headers. See the [HTTP route reference](https://supanode.xyz/docs/solana/sender/reference/http).

### QUIC

Put the key in the client certificate's first common name (`CN`). A self signed
certificate works. Follow the [QUIC connection setup](https://supanode.xyz/docs/solana/sender/reference/quic#connect) for
ALPN and server certificate verification.

<span id="refusals" />

### Declared tips and refusals

Using a key does not enable declared tips. Ask for
[declared tip access and payment](https://supanode.xyz/docs/solana/sender/api-keys) through [Supanode on Telegram](https://telegram.me/supanode_tgs) first.

A missing, unknown or revoked key returns
[`unauthorized`](https://supanode.xyz/docs/solana/sender/reference/errors#unauthorized). Support can pause a key while it
investigates; a paused key returns [`key_paused`](https://supanode.xyz/docs/solana/sender/reference/errors#key_paused) until
it's resumed. An overdue declared tip payment returns
[`payment_required`](https://supanode.xyz/docs/solana/sender/reference/errors#payment_required) on submissions; queries remain
available. Resolve payment through your agreed billing setup or
ask for help on [Supanode on Telegram](https://telegram.me/supanode_tgs).
