# Shreds and HyperShreds API

> Add, verify, list and remove Shreds and HyperShreds UDP destinations with your API key.

Canonical: https://nolimitnodes.com/docs/api-reference/shredstream/destinations-api

Shreds and HyperShreds deliver raw Solana shreds to an IPv4 address and UDP port that you control. You manage the
destinations with a small HTTPS API, authenticated with the same API key you use for RPC.

| Product | What it is | Included with |
|---|---|---|
| **Shreds** | Raw shreds over UDP. | 1 destination on **Ultra** |
| **HyperShreds** | The same shreds on our lower-latency delivery. | 1 destination on **Max**, 2 on **Enterprise** |

You can add more of either at any time. HyperShreds is **$250 a month** per destination ($2,500 a year), and extra
Shreds destinations are **$100 a month** ($1,000 a year). Contact support to buy an add-on or to change the number of
destinations on your account.

> Note: The dashboard Shredstream panel uses this same API, so destinations you add there are listed here and the other way
> round.

## Base URL and authentication

```text
https://shreds.mainnet.solana.nolimitnodes.com
```

Send your API key in the `x-api-key` header. Requests are rate limited by your plan (5 requests per second on Pro,
Ultra and Max, 10 on Enterprise).

## See what you can use

```bash
curl -s https://shreds.mainnet.solana.nolimitnodes.com/v1/shreds \
  -H "x-api-key: $NLN_API_KEY"
```

The response lists your allowance and usage for each product, and your current destinations:

```json
{
  "entitlements": {
    "shreds": { "allowed": 1, "used": 0 },
    "hypershreds": { "allowed": 0, "used": 0 }
  },
  "destinations": []
}
```

## Add a destination

```bash
curl -s -X POST https://shreds.mainnet.solana.nolimitnodes.com/v1/shreds/destinations \
  -H "x-api-key: $NLN_API_KEY" \
  -H "content-type: application/json" \
  -d '{"class": "hypershreds", "ip": "203.0.113.10", "port": 20000, "label": "trading box"}'
```

| Field | Value |
|---|---|
| `class` | `shreds` or `hypershreds` |
| `ip` | A public IPv4 address that you control |
| `port` | A UDP port from 1024 to 65535 |
| `label` | Optional name for your own reference |

The destination is created as `pending`. We send one UDP packet to the address, in the form
`SHREDCAST-VERIFY  `, to prove that you control it.

## Verify it

Listen on the port, read the token from the packet, and send it back:

```bash
# on the receiving machine
nc -u -l 20000

# then
curl -s -X POST https://shreds.mainnet.solana.nolimitnodes.com/v1/shreds/destinations/$ID/verify \
  -H "x-api-key: $NLN_API_KEY" \
  -H "content-type: application/json" \
  -d '{"token": ""}'
```

The destination becomes `active` and delivery starts. If the packet did not arrive, check your firewall and resend it:

```bash
curl -s -X POST https://shreds.mainnet.solana.nolimitnodes.com/v1/shreds/destinations/$ID/challenge \
  -H "x-api-key: $NLN_API_KEY"
```

## Remove a destination

```bash
curl -s -X DELETE https://shreds.mainnet.solana.nolimitnodes.com/v1/shreds/destinations/$ID \
  -H "x-api-key: $NLN_API_KEY"
```

Delivery stops and the slot is free to use again.

## Errors

| Status | Meaning |
|---|---|
| `400` | The class, address or port is not valid. |
| `401` | No API key was sent. |
| `403` | The account is disabled, has no Shreds or HyperShreds allowance, or the allowance is already used. |
| `404` | That destination does not belong to your account. |
| `502` | Delivery could not be reached. Try again shortly. |

## What happens when your account changes

- If your account is disabled or its plan ends, your destinations are paused automatically.
- If your allowance goes down, for example after a downgrade or when an add-on ends, the newest destinations beyond the
  new allowance are paused. They resume on their own when the allowance returns.
- A pause that we place cannot be undone from the API.