# Hướng dẫn tích hợp Robinhood Chain: Client RPC, triển khai và sự kiện

> Source: https://docs.blockvectra.com/vi/guides/robinhood-chain/

Sử dụng RPC của Robinhood Chain để kiểm tra kết nối công khai và các lệnh đọc đã xác thực, hoặc sử dụng Data API cho các bộ dữ liệu mainnet được hỗ trợ. Nhà phát triển và AI Agent sử dụng cùng các endpoint; hãy tách biệt các yêu cầu mainnet và testnet.

## Các nhiệm vụ hướng dẫn này giúp bạn hoàn thành

* [Thăm dò RPC của Robinhood Chain](#connect-with-viem-or-ethers) bằng lệnh đọc công khai sử dụng viem hoặc ethers, sau đó sử dụng key cho các phương thức có xác thực.
* [Kiểm tra kết nối RPC testnet](#testnet) bằng cách đọc `eth_chainId` trước khi thực hiện các thao tác testnet.
* [Truy vấn hoạt động cổ phiếu token hóa](#tokenized-stock-data) bằng Data API mainnet sau khi kiểm tra hỗ trợ bộ dữ liệu; các chỉ số mô tả hoạt động on-chain, không phải giá cổ phiếu.

## Truy cập RPC và WebSocket

* **URL RPC công khai**: Tìm endpoint không cần key, các phương thức công khai được hỗ trợ và giới hạn tốc độ trên [trang mainnet của Robinhood Chain](https://blockvectra.com/en/chains/robinhood_mainnet/) hoặc [trang testnet](https://blockvectra.com/en/chains/robinhood_testnet/).
* **JSON-RPC với API key**: Sử dụng các endpoint và ví dụ curl bên dưới. Đối với log, hãy xem [tài liệu tham khảo phương thức eth\_getLogs](https://docs.blockvectra.com/en/api/json-rpc/methods/eth_getLogs/) và [hướng dẫn giới hạn phạm vi khối](https://docs.blockvectra.com/en/guides/getlogs-block-range/).
* **WebSocket với API key**: Sử dụng các endpoint WebSocket bên dưới và làm theo [hướng dẫn đăng ký WebSocket](https://docs.blockvectra.com/en/guides/websocket-subscriptions/) cho `newHeads` và `logs`. Quyền truy cập RPC công khai là HTTP JSON-RPC; kết nối WebSocket yêu cầu một key.

## Thông tin mạng và các endpoint

Mỗi yêu cầu đến Robinhood Chain đều xác định rõ mạng mục tiêu của nó trong đường dẫn URL bằng cách sử dụng slug `robinhood_mainnet`. JSON-RPC hỗ trợ cả xác thực bằng key dựa trên đường dẫn và xác thực header yêu cầu (`x-api-key`), trong khi Data API phục vụ các endpoint REST dưới `/v1/data/robinhood_mainnet/`.

Các tham số và endpoint bên dưới phản ánh các tham số mạng đang hoạt động:

| Tham số / Endpoint | Giá trị / Mẫu | Xác thực |
|---|---|---|
| Chain ID (EIP-155) | `4663` | — |
| JSON-RPC (key trên đường dẫn) | `POST https://api.blockvectra.com/v1/robinhood_mainnet/{api_key}` | API key trong đường dẫn URL |
| JSON-RPC (key trong header) | `POST https://api.blockvectra.com/v1/robinhood_mainnet` | Header x-api-key: {api_key} |
| WebSocket (key trên đường dẫn) | `wss://api.blockvectra.com/v1/robinhood_mainnet/{api_key}` | API key trong đường dẫn URL |
| WebSocket (key trong header) | `wss://api.blockvectra.com/v1/robinhood_mainnet` | Header x-api-key: {api_key} hoặc Authorization: Bearer {api_key} |
| Đăng ký WebSocket | `newHeads, logs` | — |
| Gốc Data API | `GET https://api.blockvectra.com/v1/data/robinhood_mainnet/…` | Header x-api-key: {api_key} |
| Trạng thái công khai | `GET https://api.blockvectra.com/v1/status` | Không xác thực (công khai) |

## Kết nối với viem hoặc ethers

Nhà phát triển và AI Agent có thể sử dụng cùng các cài đặt phía máy chủ. Sử dụng Node.js 24 trở lên, viem 2 hoặc ethers 6, và bắt đầu với các lệnh đọc công khai. Thiết lập `BLOCKVECTRA_API_KEY` một cách an toàn trong môi trường cho các phương thức có key và WebSocket. Giữ các key và URL RPC chứa key ngoài mã trình duyệt, log và hệ thống quản lý phiên bản.

Lưu tệp này dưới dạng `network.mjs`. Bắt đầu trên testnet; đặt `BLOCKVECTRA_CHAIN=robinhood_mainnet` để chuyển sang mainnet. Nó đọc `chain_id` và chính sách phương thức từ [GET /v1/chains](https://api.blockvectra.com/v1/chains). Đối với các lệnh đọc không cần key, hãy sử dụng `public.url` của danh mục và chỉ các phương thức được liệt kê trong `public.methods`; tính khả dụng của HTTP công khai không đồng nghĩa với quyền truy cập WebSocket.

```js
const chainSlug = process.env.BLOCKVECTRA_CHAIN ?? 'robinhood_testnet';
const key = process.env.BLOCKVECTRA_API_KEY;
const catalogUrl = 'https://api.blockvectra.com/v1/chains';
const response = await fetch(catalogUrl, { signal: AbortSignal.timeout(15_000) });
if (!response.ok) throw new Error(`Chains HTTP ${response.status}`);
const catalog = await response.json();
export const chainInfo = catalog.chains.find(item => item.chain === chainSlug);
if (!chainInfo || !Number.isSafeInteger(chainInfo.chain_id) || chainInfo.chain_id <= 0) {
  throw new Error('Missing chain or chain_id');
}
export function allows(method) {
  const matches = pattern => pattern.endsWith('*')
    ? method.startsWith(pattern.slice(0, -1)) : pattern === method;
  if (!key) return (chainInfo.public?.methods ?? []).some(matches);
  return (chainInfo.methods?.allow ?? []).some(matches)
    && !(chainInfo.methods?.deny ?? []).some(matches);
}
if (!allows('eth_chainId')) throw new Error('eth_chainId is unavailable');
export const rpcUrl = key
  ? new URL(`./${chainSlug}/${encodeURIComponent(key)}`, catalogUrl).href
  : chainInfo.public?.url;
if (!rpcUrl) throw new Error('Public RPC is unavailable; set BLOCKVECTRA_API_KEY');
```

Lưu thành `viem-client.mjs`, cài đặt bằng `npm install viem@2`, sau đó chạy `node viem-client.mjs`.

```js
import { createPublicClient, defineChain, http } from 'viem';
import { chainInfo, rpcUrl } from './network.mjs';

export const chain = defineChain({
  id: chainInfo.chain_id,
  name: chainInfo.name,
  nativeCurrency: { name: 'ETH', symbol: 'ETH', decimals: 18 },
  rpcUrls: { default: { http: [rpcUrl] } },
});
export const client = createPublicClient({ chain, transport: http(rpcUrl) });
if (await client.getChainId() !== chain.id) throw new Error('RPC chain ID mismatch');
console.log(await client.getBlockNumber());
```

Đối với ethers, lưu thành `ethers-client.mjs`, cài đặt bằng `npm install ethers@6`, sau đó chạy `node ethers-client.mjs`.

```js
import { JsonRpcProvider } from 'ethers';
import { chainInfo, rpcUrl } from './network.mjs';

const provider = new JsonRpcProvider(rpcUrl, chainInfo.chain_id, { batchMaxCount: 1 });
const network = await provider.getNetwork();
if (network.chainId !== BigInt(chainInfo.chain_id)) throw new Error('RPC chain ID mismatch');
console.log(await provider.getBlockNumber());
provider.destroy();
```

## Triển khai với Foundry hoặc Hardhat

Nạp tiền cho người triển khai bằng test ETH qua [faucet testnet](https://docs.blockvectra.com/en/guides/robinhood-testnet-faucet/) trước; các giao dịch mainnet cần ETH mainnet. [Hướng dẫn triển khai và mạng chính thức](https://docs.robinhood.com/chain/deploy-smart-contracts/) liệt kê Chain ID của mainnet và testnet (truy cập: 2026-10-07). Các bảng endpoint trên trang này sử dụng `/v1/chains`.

Xuất URL và Chain ID đã chọn từ `network.mjs`. Kiểm tra `eth_sendRawTransaction` đối chiếu với `methods.allow` và `methods.deny` trước khi phát sóng.

```bash
export RPC_URL="$(node --input-type=module -e "import { rpcUrl, allows } from './network.mjs'; if (!allows('eth_sendRawTransaction')) throw new Error('Broadcast unavailable'); console.log(rpcUrl)")"
export CHAIN_ID="$(node --input-type=module -e "import { chainInfo } from './network.mjs'; console.log(chainInfo.chain_id)")"
```

Tiếp tục với [hướng dẫn triển khai Foundry hoặc Hardhat](https://docs.blockvectra.com/en/guides/deploy-contract/) dùng chung cho `Hello.sol`, cài đặt công cụ, phát sóng và kiểm tra biên lai.

## Lắng nghe sự kiện hợp đồng qua WebSocket

Lưu thành `watch-logs.mjs` và đặt `LOG_ADDRESS` thành hợp đồng đã triển khai hoặc hợp đồng token bạn theo dõi. Chạy `node watch-logs.mjs`. Mã kiểm tra `ws` và `subscriptions` từ `/v1/chains` trước khi đăng ký nhận `logs`.

```js
import { createPublicClient, webSocket, isAddress } from 'viem';
import { chain } from './viem-client.mjs';
import { chainInfo, rpcUrl } from './network.mjs';

if (!process.env.BLOCKVECTRA_API_KEY) throw new Error('WebSocket requires BLOCKVECTRA_API_KEY');
const address = process.env.LOG_ADDRESS;
if (!chainInfo.ws || !chainInfo.subscriptions?.includes('logs')) {
  throw new Error('WebSocket logs are unavailable; use HTTP backfill or webhook push');
}
if (!address || !isAddress(address)) throw new Error('Set LOG_ADDRESS');
const wsUrl = new URL(rpcUrl);
wsUrl.protocol = 'wss:';
const client = createPublicClient({ chain, transport: webSocket(wsUrl.href) });
const unwatch = client.watchEvent({
  address, poll: false,
  onLogs: logs => console.log(logs),
  onError: error => console.error(error),
});
process.once('SIGINT', () => { unwatch(); process.exit(0); });
```

Sau khi listener khởi động, hãy gửi giao dịch `ping()` từ một terminal khác bằng cách sử dụng các biến triển khai đã xuất tương tự:

```bash
cast send "$CONTRACT_ADDRESS" "ping()" --rpc-url "$RPC_URL" \
  --private-key "$DEPLOYER_PRIVATE_KEY"
```

Lưu bền vững khối đã xử lý gần nhất và loại bỏ trùng lặp theo `(blockHash, transactionHash, logIndex)`. Sau khi kết nối lại, hãy backfill các khối bị bỏ lỡ bằng các yêu cầu `eth_getLogs` có giới hạn; đối chiếu các log được đánh dấu `removed` khi có reorg. Xem [Đăng ký WebSocket](https://docs.blockvectra.com/en/guides/websocket-subscriptions/) và [giới hạn phạm vi khối](https://docs.blockvectra.com/en/guides/getlogs-block-range/).

Đối với các sự kiện địa chỉ được chuyển phát đến đầu nhận HTTPS của bạn, **GET /v1/push/chains liệt kê các chuỗi được hỗ trợ** và cài đặt số xác nhận; sử dụng header `x-api-key`. Làm theo [hướng dẫn webhook push](https://docs.blockvectra.com/en/guides/webhook-push/) để biết về đăng ký, xác minh chữ ký, loại bỏ trùng lặp và phát lại. Đối với các truy vấn hoạt động của token cổ phiếu mainnet, hãy tiếp tục với [hướng dẫn cổ phiếu](https://docs.blockvectra.com/en/guides/stocks/).

## Các ví dụ curl trực tiếp

Bạn có thể thực hiện các lệnh gọi JSON-RPC ngay lập tức bằng các HTTP client tiêu chuẩn. Thay thế `{api_key}` bằng API key BlockVectra của bạn:

**eth_chainId (Header)**

Truy vấn Chain ID EIP-155 bằng cách sử dụng header yêu cầu `x-api-key`:

```bash
curl -s "https://api.blockvectra.com/v1/robinhood_mainnet" \
  -H "Content-Type: application/json" \
  -H "x-api-key: {api_key}" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_chainId","params":[]}'
```


  **eth_blockNumber (Path)**

Truy vấn số hiệu khối mới nhất bằng cách truyền API key của bạn trong đường dẫn URL:

```bash
curl -s "https://api.blockvectra.com/v1/robinhood_mainnet/{api_key}" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'
```


### Cấu trúc phản hồi

Các phản hồi tuân theo đặc tả JSON-RPC 2.0:

* **Thành công**: Trả về một khung phản hồi với `jsonrpc: "2.0"`, cùng `id`, và một chuỗi `result` chứa số lượng được mã hóa thập lục phân (`eth_chainId` trả về Chain ID mã hóa hex; `eth_blockNumber` trả về chiều cao khối mới nhất).
* **Phương thức không được phép**: Yêu cầu một phương thức nằm ngoài các phương thức được phép của mạng trả về mã lỗi JSON-RPC `-32601` (`method not available`, không tính phí).
* **Truy vấn ngoài cửa sổ**: Các yêu cầu trạng thái lịch sử sớm hơn cửa sổ lưu giữ trạng thái trả về mã lỗi JSON-RPC `-32011` (không tính phí).
* **Tham số không hợp lệ**: Các tham số yêu cầu không đúng định dạng hoặc không được phép trả về mã lỗi JSON-RPC `-32602` (không tính phí).

## Năng lực và chính sách phương thức

Các phương thức JSON-RPC khả dụng, giới hạn phạm vi khối log và việc lưu giữ trạng thái lịch sử trên Robinhood Chain được công bố động qua `GET /v1/chains`. Việc trace thực thi (`debug_trace*`, bao gồm `debug_traceTransaction`) được quản lý bởi chính sách phương thức của chuỗi:

### Thông số mạng và giới hạn

- **Phạm vi khối eth_getLogs**: Tối đa 1000 khối mỗi yêu cầu
- **Cửa sổ trạng thái lịch sử**: 900 khối gần đây (truy vấn ngoài phạm vi trả về -32011)
- **Truy vết thực thi (debug_trace*)**: Được hỗ trợ (debug_traceTransaction, debug_traceCall, debug_traceBlockByNumber, debug_traceBlockByHash)

Phương thức được cho phép theo từng chuỗi: [Chuỗi được hỗ trợ](https://docs.blockvectra.com/en/chains/)

## Testnet

Để nhận test ETH cho các giao dịch, hãy xem [hướng dẫn faucet testnet của Robinhood Chain](https://docs.blockvectra.com/en/guides/robinhood-testnet-faucet/).

Testnet của Robinhood Chain (Chain ID: 46630) sử dụng cùng API key như mainnet tại endpoint `https://api.blockvectra.com/v1/robinhood_testnet`, được xác thực qua header yêu cầu `x-api-key`.

Các yêu cầu testnet sử dụng cùng trọng số CU như mainnet và được trừ từ cùng số dư và tín dụng miễn phí. Các phương thức JSON-RPC khả dụng và việc lưu giữ trạng thái lịch sử trên Testnet của Robinhood Chain được công bố động qua `GET /v1/chains`.

Để có tài liệu khởi đầu ba bước có thể chạy được nhằm đọc testnet không cần key, truyền luồng log qua WebSocket, rồi chuyển cùng key đó sang mainnet, hãy xem [Hướng dẫn khởi đầu Testnet của Robinhood Chain](https://docs.blockvectra.com/en/guides/robinhood-testnet-starter/).

```bash
curl -s "https://api.blockvectra.com/v1/robinhood_testnet" \
  -H "Content-Type: application/json" \
  -H "x-api-key: {api_key}" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_chainId","params":[]}'
```

Phản hồi mong đợi:

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

| Tham số / Endpoint | Giá trị / Mẫu | Xác thực |
|---|---|---|
| Chain ID (EIP-155) | `46630` | — |
| JSON-RPC (key trên đường dẫn) | `POST https://api.blockvectra.com/v1/robinhood_testnet/{api_key}` | API key trong đường dẫn URL |
| JSON-RPC (key trong header) | `POST https://api.blockvectra.com/v1/robinhood_testnet` | Header x-api-key: {api_key} |
| WebSocket (key trên đường dẫn) | `wss://api.blockvectra.com/v1/robinhood_testnet/{api_key}` | API key trong đường dẫn URL |
| WebSocket (key trong header) | `wss://api.blockvectra.com/v1/robinhood_testnet` | Header x-api-key: {api_key} hoặc Authorization: Bearer {api_key} |
| Đăng ký WebSocket | `newHeads, logs` | — |
| Gốc Data API | `Chưa khả dụng` | — |
| Trạng thái công khai | `GET https://api.blockvectra.com/v1/status` | Không xác thực (công khai) |

### Thông số mạng và giới hạn

- **Phạm vi khối eth_getLogs**: Tối đa 1000 khối mỗi yêu cầu
- **Cửa sổ trạng thái lịch sử**: 1023 khối gần đây (truy vấn ngoài phạm vi trả về -32011)
- **Truy vết thực thi (debug_trace*)**: Được hỗ trợ (debug_traceTransaction, debug_traceCall, debug_traceBlockByNumber, debug_traceBlockByHash)

Phương thức được cho phép theo từng chuỗi: [Chuỗi được hỗ trợ](https://docs.blockvectra.com/en/chains/)

## Dữ liệu cổ phiếu token hóa

Trên Robinhood Chain, BlockVectra Data API cung cấp các chỉ số on-chain hàng ngày và siêu dữ liệu cho các cổ phiếu token hóa trên hai endpoint:

* **Bảng xếp hạng hàng ngày (`GET /v1/data/robinhood_mainnet/stocks`)**: Bảng xếp hạng hoạt động hàng ngày của các cổ phiếu token hóa cho một ngày UTC cụ thể, được sắp xếp theo hoạt động chuyển giao giảm dần.
* **Lấy một cổ phiếu token hóa (`GET /v1/data/robinhood_mainnet/stocks/{token}`)**: Siêu dữ liệu hợp đồng token và tối đa 30 ngày các chỉ số hàng ngày gần đây theo địa chỉ token.

Để biết chi tiết các tham số yêu cầu, khung phản hồi (`StockDailyListEnvelope` và `StockTokenEnvelope`), ghi chú phân trang và ước tính mức tiêu thụ CU, hãy xem [Hướng dẫn cổ phiếu token hóa](https://docs.blockvectra.com/en/guides/stocks/).

Starter template hoàn chỉnh: [blockvectra/robinhood-stock-tokens](https://github.com/blockvectra/robinhood-stock-tokens)

## Bắt đầu và API key

Tài khoản mới nhận 30,000,000 CU khi đăng ký — không cần thẻ tín dụng.

Bạn có thể thử endpoint công khai không cần key `https://api.blockvectra.com/v1/robinhood_mainnet/public` trước (chỉ các phương thức JSON-RPC ví, Data API yêu cầu một key; các phương thức và giới hạn phải tuân theo `/v1/chains`); hãy đăng ký tài khoản nếu bạn cần giới hạn tốc độ cao hơn.

* **Web console**: Đăng ký qua chữ ký ví Ethereum, và tạo một API key trong [Console](https://console.blockvectra.com/login/?next=%2Fkeys%2F). Xem [Hướng dẫn bắt đầu nhanh](https://docs.blockvectra.com/en/quickstart/) để biết chi tiết thiết lập.
* **Đăng ký theo chương trình**: Các AI Agent tự hành, script tự động và quy trình CI có thể đăng nhập và cung cấp API key bằng chữ ký ví Ethereum (EIP-191) mà không cần trình duyệt. Làm theo [Hướng dẫn đăng ký theo chương trình](https://docs.blockvectra.com/en/guides/programmatic-signup/).
* **AI Agent**: Các AI Agent tự hành có thể khám phá khả năng của Robinhood Chain bằng máy chủ Model Context Protocol (MCP) chính thức. Xem [Kết nối AI Agent với BlockVectra](https://docs.blockvectra.com/en/guides/ai-agents/).
* **Nâng cấp giới hạn**: Sau khi nạp tiền, giới hạn số lệnh gọi mỗi giây trên toàn tài khoản sẽ được gỡ bỏ; mỗi key vẫn phải tuân theo giới hạn tốc độ và burst của Compute Unit (CU). Để biết mức giá và đơn vị thanh toán hiện tại, hãy xem [Trang bảng giá](https://blockvectra.com/en/pricing/).

## Các bước tiếp theo

* [Khám phá danh mục bộ dữ liệu](https://blockvectra.com/en/data/) để xem mọi bộ dữ liệu mà BlockVectra lập chỉ mục.
* [Xem gói miễn phí và bảng giá](https://blockvectra.com/en/pricing/#free) để kiểm tra những gì tài khoản của bạn bao gồm.
* [Đăng nhập vào console](https://console.blockvectra.com/login/?next=%2Fkeys%2F) để tạo API key.