Use Multichain API

Create a multichain endpoint on Chainstack, attach your Global Nodes and Dedicated Nodes, and call every attached node with one auth token.

Multichain API gives you one auth token for several nodes. You create a multichain endpoint on Chainstack, attach the Global Nodes and Dedicated Nodes you want, and put the multichain auth token in the URL of each node instead of managing one auth token per node.

Multichain API is available on every plan, including the Developer plan.

What is a multichain endpoint?

A multichain endpoint is a named group of your existing nodes with one shared multichain auth token:

• The multichain auth token authorizes requests to each node in the group, so you keep a single secret in your environment variables or CI instead of one per node.
• Your nodes keep their own endpoint URLs and auth tokens, and those auth tokens keep working.

A multichain endpoint can hold the following:

• One Global Node per protocol and network
• Any number of Dedicated Nodes

You can’t attach Trader Nodes. The same node can belong to several multichain endpoints.

Create a multichain endpoint

1. Open Multichain API

   On Chainstack, click Multichain API in the left menu.

2. Name the multichain endpoint

   Click Create endpoint, enter a name of up to 30 characters, and click Create endpoint in the dialog. The name field starts with your organization name and the current date and time, which you can keep or replace.

After you create a multichain endpoint:

• The multichain endpoint has a multichain auth token and no nodes, so the multichain auth token authorizes nothing until you attach a node.
• The Multichain API page lists the multichain endpoint with its node count, a shortened multichain auth token, and the creation date.

Attach nodes to a multichain endpoint

1. Open the multichain endpoint

   On Chainstack, click Multichain API and click the name of the multichain endpoint.

2. Add the nodes

   Under Connected nodes, click Add node. Search for a node by name or filter the list by type (Global or Dedicated), and click Add next to each node you want. Click Done when finished.

When you manage the nodes of a multichain endpoint:

• You can add or remove nodes at any time, and the multichain auth token stays the same.
• Chainstack dims a node that you can’t add. Hover over the node’s Add button to see the reason, for example, that a multichain endpoint can’t hold two Global Nodes for the same protocol and network.

Call a node with the multichain auth token

The multichain auth token takes the place of the node’s own auth token in the node’s endpoint URLs. To get a URL:

1. Open the multichain endpoint.
2. Select a node under Connection details.
3. Copy the URL you need. The URL already contains the multichain auth token.

How you use the multichain auth token depends on the node and the endpoint:

• Global Node — the URL uses the core.chainstack.com host with the protocol and network in the subdomain.
• Dedicated Node — the URL uses the node’s own host, so copy the URL from Connection details instead of building it yourself.
• REST API — the multichain auth token sits before the API path, the same as a node’s auth token.
• gRPC endpoint — use the node’s own x-token, as described in gRPC access via x-token.
• Node that is stopped or in maintenance — you can attach the node, but Connection details shows no URLs for the node until it is running again.

To call attached Ethereum Mainnet, Solana Mainnet, and Aptos Mainnet Global Nodes with one multichain auth token, put the multichain auth token in each node’s URL:

cURL

export CHAINSTACK_MULTICHAIN_TOKEN="YOUR_MULTICHAIN_AUTH_TOKEN"

curl -X POST "https://ethereum-mainnet.core.chainstack.com/$CHAINSTACK_MULTICHAIN_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

curl -X POST "https://solana-mainnet.core.chainstack.com/$CHAINSTACK_MULTICHAIN_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"getSlot","params":[],"id":1}'

curl "https://aptos-mainnet.core.chainstack.com/$CHAINSTACK_MULTICHAIN_TOKEN/v1"

Replace YOUR_MULTICHAIN_AUTH_TOKEN with the multichain auth token from the multichain endpoint’s page. Each call returns the protocol’s normal response: a JSON-RPC result for Ethereum and Solana, and the ledger information for Aptos.

A request to an attached node returns a normal response. A request to a node that isn’t attached returns 401 Unauthorized.

How Chainstack handles requests with the multichain auth token

• A request with the multichain auth token gets the same handling as a request with the node’s own auth token, so the node’s rate limits and access rules apply.
• A request with the multichain auth token to a node that isn’t attached to the multichain endpoint returns 401 Unauthorized with the message Access token missing or invalid. Make sure you are using the correct node endpoint.
• A WSS connection with the multichain auth token to a node that isn’t attached fails with 401 during the handshake.
• When you delete a node on Chainstack, Chainstack removes the node from its multichain endpoints. The multichain endpoints and their multichain auth tokens stay.
• Removing the last node from a multichain endpoint leaves the multichain endpoint and its multichain auth token in place with no nodes.

Find the multichain auth token

The multichain auth token starts with mt_. To copy the multichain auth token, use either of the following:

• The multichain endpoint’s page — the full multichain auth token is always under API key, and Copy puts it on your clipboard.
• The Multichain API page — the list shows a shortened multichain auth token, and its copy icon copies the full value.

Treat the multichain auth token as a secret. See Best practices for securing your Chainstack endpoint for guidance.

Replace a multichain auth token

You can’t rotate the multichain auth token of a multichain endpoint. To replace the multichain auth token, for example after it leaks:

1. Create a new multichain endpoint

   Create a multichain endpoint and attach the same nodes to it.

2. Update your applications

   Switch your environment variables or CI secrets to the new multichain auth token.

3. Delete the old multichain endpoint

   Delete the old multichain endpoint, as described in Remove a node or delete a multichain endpoint.

Remove a node or delete a multichain endpoint

To remove a node from a multichain endpoint, do one of the following:

• Open the multichain endpoint and click the trash icon next to the node under Connected nodes.
• Click Remove next to the node in the Add nodes dialog.

After you remove a node:

• Requests to the removed node with the multichain auth token return 401 Unauthorized.
• The other nodes in the multichain endpoint keep working.

To delete a multichain endpoint:

1. Click Delete endpoint on the multichain endpoint’s page, or hover over the multichain endpoint’s row on the Multichain API page and click the trash icon.
2. In the Delete endpoint dialog, click Yes, I’m sure. If the multichain endpoint has nodes, the dialog shows how many nodes the multichain auth token stops working on.

After you delete a multichain endpoint:

• The multichain auth token stops working on every attached node.
• You can’t undo the deletion.
• Your nodes stay as they are.