MAINNET SUPPORTED TESTNET SUPPORTED
Turbo pipelines provide high-performance streaming data pipelines with sub-second latency. Deploy a pipeline to start streaming Stellar data to your preferred destination. ### Quick config ```yaml stellar-transactions.yaml theme={null} name: my-stellar-transactions resource_size: s sources: stellar_transactions: type: dataset dataset_name: stellar_mainnet.transactions version: 1.2.0 start_at: latest sinks: my_sink: type: postgres from: stellar_transactions schema: public table: stellar_transactions secret_name: MY_POSTGRES_SECRET primary_key: transaction_hash ``` Deploy with: ```bash theme={null} goldsky turbo apply stellar-transactions.yaml ``` ### Available chain slugs Mainnet: `stellar_mainnet` | Testnet: `stellar_testnet` Goldsky provides real-time (under 5 seconds) streaming of Stellar datasets, including all historical data, for both mainnet and testnet. Datasets include ledgers, transactions, operations, events, transfers, ledger entries, and balances.per-campaign table)] T -->|4. poll /state every 2s| P T -->|5. read snapshot via SQL| DB T -->|6. pay each holder (25 concurrent)| C T -->|7. read escrowRemaining| C T -->|8. DELETE pipeline + drop table| P ``` One HTTP request drives the entire lifecycle. No cron, no off-chain handoff: 1. The operator declares a distribution by `POST`ing `{ campaignId, recordBlock, totalAmount }`. The task validates `recordBlock <= currentBlock`, approves USDC, and calls `DistributionCampaign.declare()`, which atomically pulls the escrow. 2. The same task spawns a job-mode Turbo pipeline filtered to the share-token contract over `block_number BETWEEN
against Gateway contract Agent->>Edge: POST + Payment-Signature header Edge->>Circle: Settle 5 atomic USDC ($0.000005) Circle-->>Edge: Settlement OK Edge-->>Agent: 200 + JSON-RPC result ``` x402 is designed for autonomous agents. SDK clients handle the full handshake transparently. ## Pricing **\$5 per million requests, all methods, all chains.** Each call debits 5 atomic USDC (\$0.000005) from your Circle Gateway balance. Settlement is gasless on your side, and Circle batches settlements on Goldsky's side. ## Endpoint Edge RPC endpoints follow a single URL pattern, with the chain ID in the path: ``` https://edge.goldsky.com/standard/evm/{chainId} ``` To discover every chain Edge serves, hit `edge.goldsky.com` with no path. It returns a JSON list of every supported network, with CAIP id, alias, block time, and health status: ```bash theme={null} curl https://edge.goldsky.com | jq '.standard[] | {id, alias, state}' # {"id": "evm:1", "alias": "ethereum-mainnet", "state": "OK"} # {"id": "evm:8453", "alias": "base", "state": "OK"} # {"id": "evm:42161", "alias": "arbitrum", "state": "OK"} # ... ``` ## Supported chains for x402 payments You can pay over x402 on any chain Circle Gateway currently advertises. The 11 networks below mirror the live list at [`https://gateway-api.circle.com/v1/x402/supported`](https://gateway-api.circle.com/v1/x402/supported); Edge serves additional chains that aren't yet in this list, and those still require a regular API key. | Network | CAIP id | USDC contract | | ----------------- | -------------- | -------------------------------------------- | | Ethereum | `eip155:1` | `0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48` | | Base | `eip155:8453` | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` | | Arbitrum One | `eip155:42161` | `0xaf88d065e77c8cC2239327C5EDb3A432268e5831` | | Optimism | `eip155:10` | `0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85` | | Polygon | `eip155:137` | `0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359` | | Avalanche C-Chain | `eip155:43114` | `0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E` | | Unichain | `eip155:130` | `0x078D782b760474a361dDA0AF3839290b0EF57AD6` | | Sonic | `eip155:146` | `0x29219dd400f2Bf60E5a23d13Be72B486D4038894` | | World Chain | `eip155:480` | `0x79A02482A880bCE3F13e09Da970dC34db4CD24d1` | | Sei EVM | `eip155:1329` | `0xe15fC38F6D8c56aF07bbCBe3BAf5708A2Bf42392` | | HyperEVM | `eip155:999` | `0xb88339CB7199b77E23DB6E890353E22632Ba630f` | You only need a Circle Gateway USDC deposit on **one** of these chains. The endpoint advertises every chain in its 402 response, and SDK clients pick whichever you're funded on. ## Quickstart ### 1. Fund a Circle Gateway deposit Use the [Circle Gateway dashboard](https://developers.circle.com/gateway), or do it directly via the SDK: ```ts theme={null} import { GatewayClient } from "@circle-fin/x402-batching/client"; const gateway = new GatewayClient({ chain: "base", // any supported chain privateKey: process.env.PK as `0x${string}`, }); await gateway.deposit("1"); // 1 USDC = 200,000 Edge requests ``` Your deposit takes a few minutes to reflect in Circle's `/v1/balances` API after the on-chain transaction confirms. ### 2. Pay for an Edge request `pay()` handles the full 402 → sign → retry flow for you: ```ts theme={null} const { data, formattedAmount, transaction } = await gateway.pay( "https://edge.goldsky.com/standard/evm/1", { method: "POST", headers: { "content-type": "application/json" }, body: { jsonrpc: "2.0", id: 1, method: "eth_chainId", params: [] }, }, ); console.log("paid", formattedAmount, "USDC →", JSON.stringify(data)); // paid 0.000005 USDC → {"jsonrpc":"2.0","id":1,"result":"0x1"} ``` That's it. No Goldsky account, no secret query parameter, no invoice. Your wallet address becomes your identity for rate limiting and metrics. ## How it works x402 is an HTTP protocol layered on top of standard requests. The full handshake:
```mermaid theme={null}
stateDiagram-v2
state ACTIVE {
[*] --> STARTING
STARTING --> RUNNING
}
```
Let's look at a simple example below where we configure a pipeline that consumes Logs from Base chain and streams them into a Postgres database:
```yaml base-logs.yaml theme={null}
name: base-logs-pipeline
resource_size: s
apiVersion: 3
sources:
base.logs:
dataset_name: base.logs
version: 1.0.0
type: dataset
description: Enriched logs for events emitted from contracts. Contains the contract address, data, topics, decoded event and metadata for blocks and transactions.
display_name: Logs
transforms: {}
sinks:
postgres_base_logs:
type: postgres
table: base_logs
schema: public
secret_name: GOLDSKY_SECRET
description: "Postgres sink for: base.logs"
from: base.logs
```
Let's attempt to run it using the command `goldsky pipeline apply base-logs.yaml --status ACTIVE` or `goldsky pipeline start base-logs.yaml`
```
❯ goldsky pipeline apply base-logs.yaml --status ACTIVE
│
◇ Successfully validated config file
│
◇ Successfully applied config to pipeline: base-logs-pipeline
To monitor the status of your pipeline:
Using the CLI: `goldsky pipeline monitor base-logs-pipeline`
Using the dashboard: https://app.goldsky.com/dashboard/pipelines/stream/base-logs-pipeline/1
```
At this point we have set the desired status to `ACTIVE`. We can confirm this using `goldsky pipeline list`:
```
❯ goldsky pipeline list
✔ Listing pipelines
────────────────────────────────────────
│ Name │ Version │ Status │ Resource │
│ │ │ │ Size │
│───────────────────────────────────────
│ base-logs-pipeline │ 1 │ ACTIVE │ s │
────────────────────────────────────────
```
We can then check the runtime status of this pipeline using the `goldsky pipeline monitor base-logs-pipeline` command:
```mermaid theme={null}
---
title: Healthy pipeline becomes unhealthy
---
stateDiagram-v2
state status:ACTIVE {
[*] --> STARTING
STARTING --> RUNNING
RUNNING --> FAILING
FAILING --> TERMINATED
}
```
```mermaid theme={null}
---
title: Pipeline cannot start
---
stateDiagram-v2
state status:ACTIVE {
[*] --> STARTING
STARTING --> FAILING
FAILING --> TERMINATED
}
```
A Pipeline can be in an `ACTIVE` desired status but a `TERMINATED` runtime status in scenarios that lead to terminal failure.
Let's see an example where we'll use the same configuration as above but set a `secret_name` that does not exist.
```yaml bad-base-logs.yaml theme={null}
name: bad-base-logs-pipeline
resource_size: s
apiVersion: 3
sources:
base.logs:
dataset_name: base.logs
version: 1.0.0
type: dataset
description: Enriched logs for events emitted from contracts. Contains the contract address, data, topics, decoded event and metadata for blocks and transactions.
display_name: Logs
transforms: {}
sinks:
postgres_base_logs:
type: postgres
table: base_logs
schema: public
secret_name: YOUR_DATABASE_SECRET
description: "Postgres sink for: base.logs"
from: base.logs
```
Let's start it using the command `goldsky pipeline apply bad-base-logs.yaml`.
```
❯ goldsky pipeline apply bad-base-logs.yaml
│
◇ Successfully validated config file
│
◇ Successfully applied config to pipeline: base-logs-pipeline
To monitor the status of your pipeline:
Using the CLI: `goldsky pipeline monitor bad-base-logs-pipeline`
Using the dashboard: https://app.goldsky.com/dashboard/pipelines/stream/bad-base-logs-pipeline/1
```
The pipeline configuration is valid, however, the pipeline runtime will encounter error since the secret that contains credentials to communicate with the sink does not exist.
Running `goldsky pipeline monitor bad-base-logs-pipeline` we see: