Conduit

What it does

Conduit connects an application to a configured Solana RPC provider. It supplies bounded wallet, token and activity reads, optional transaction transport, a network check and an owner-facing connection workspace.

Use it instead of distributing backend-only credentials or running a chain-scale indexer on the device. Conduit is an HTTP RPC client, not an oracle, market-price service or a WebSocket subscription API. Selecting an endpoint does not make its returned data authenticated business evidence.

Use independently

Select uk.capp.sidecar.solana-conduit. For a first read, choose direct-rpc, the intended network and an endpoint that permits your client environment. Keep allowWriteMethods off. Use window.capp.solana.conduit or the portable client.

Use an endpoint/token explicitly suitable for distribution to clients. A configured rpcToken is sent as x-token; a packaged token is extractable. Place backend-only secrets behind your own appropriately authorized service, not in the app or a public example.

Provider dependencies

The other Sidecars are not needed to inspect balances. Live Edge additionally requires writable devnet Conduit, but enabling transport writes does not itself authorize a wallet or payment. Testnet may be configured for raw RPC; wallet/asset convenience helpers accept devnet and mainnet-beta only.

First successful connection

1. Configure the intended endpoint and network in Library. For device editing, opt into allowRuntimeRpcSettings with direct-rpc before packaging.
2. Read status(): inspect ready, readiness, error, the write flags and lastRequestError. A configured/unverified endpoint is not a completed request.
3. Use inspect({target: primary, method: getVersion}) or the settings workspace's Node version action for a harmless connectivity read.
4. For devnet, call verifyNetwork() and inspect the observed genesis hash. This method verifies devnet specifically; it is not a generic mainnet/testnet attestation.
5. Read a wallet balance. Keep the observed slot and time with the value, and show unavailable data as unavailable rather than zero.

The optional Test & use connection operation checks before adopting changes. Runtime editing cannot change build-owned network or write permissions. Remember persists connection settings on that device, including the client token; leaving it unchecked applies a session choice. Changing an endpoint does not clear wallets or payment attempts.

A read-only wallet observation

Copy the client module beside this module. Call it from Refresh balance, with an actual public address; do not automatically poll rapidly. No wallet connection or signature is needed.

import {createSolanaClient} from './solana-client.mjs';
const client = createSolanaClient(() => window.capp?.solana);

export async function readDevnetBalance(walletPubkey) {
  const status = await client.call('conduit', 'status');
  if (!status.ready || status.providerMode === 'offline') {
    throw new Error('Configure an available Conduit read connection');
  }
  const result = await client.call('conduit', 'balance', {network: 'devnet', walletPubkey});
  return {walletPubkey: result.walletPubkey, network: result.network,
    lamports: result.value, slot: result.slot, genesisHash: result.genesisHash,
    observedAt: result.observedAt};
}

The helper itself verifies the configured connection's genesis before returning the balance. A failed read rejects; the example never substitutes 0. observedAt is milliseconds here. Other component timestamps can be seconds—use the method's contract, not a global assumption.

Bounded reads and transport writes

request() accepts a declared method, array params and matching network, not an arbitrary URL or header map. It returns the JSON-RPC result, not the full envelope. simulateTransaction is an allowed simulation method, not a payment submission.

sendTransaction and requestAirdrop require allowWriteMethods; mainnet writes additionally require allowMainnetWrites. Conduit does not provide wallet approval or a submission-attempt ledger. Prefer Dispatch/Edge for transaction delivery and recovery. Never retry a send merely because an HTTP reply disappeared.

tokenAccounts() has a returned-row limit and reports truncated/totalReturned. That is not a server-side token-account cursor or a promise that the provider scanned only that many accounts. Unsupported accounts remain labelled supported: false; Token-2022 is excluded. asset() reports decoded mint/account observations and metadataAuthenticated: false, not an issuer-verified logo, symbol or price.

activity() uses bounded signature history and before/until cursors. transaction() is a single observation: check available and state before consuming bytes. It does not wait until a transaction appears or verify a merchant payment by itself.

Scope and limitations

Requests are serialized and limited by the configured ceiling. With queueRequests off, exceeding it is a rejection; with it on, calls wait for the local rate window. Provider HTTP 429 responses can impose a cooldown regardless. Bound your application's outstanding requests and stop polling when its view is removed; there is no public per-request cancellation or subscription interface to invent.

Transport omits ambient credentials, rejects redirects and enforces time/response-size limits. These controls do not make arbitrary remote output trustworthy. Logs and connection exports can still disclose account activity or endpoint details; inspect them before sharing.

Application API

The owning interface is window.capp.solana.conduit. The portable client calls the same methods. This table describes main arguments, not a stricter typed guarantee than the current provider implements. Exact transaction/provider bindings must be preserved; unsupported state or arguments are rejected.

import {createSolanaClient} from './solana-client.mjs';
const client = createSolanaClient(() => window.capp?.solana);
const status = await client.call('conduit', 'status');

status

client.call('conduit', 'status', input)

Main input: No arguments required.

Read configured mode, network, limits and transport readiness without exposing credential values.

request

client.call('conduit', 'request', input)

Main input: method, params; network where required by the selected provider.

Perform an allowed RPC request through the configured connection. The method allowlist and write gates still apply.

verifyNetwork

client.call('conduit', 'verifyNetwork', input)

Main input: No arguments required.

Check the configured network against observed genesis identity. It does not authorize a transaction.

inspect

client.call('conduit', 'inspect', input)

Main input: method; optional target: primary or read-only.

Run a supported connection diagnostic such as node version, slot, block height or genesis hash.

openSettings

client.call('conduit', 'openSettings', input)

Main input: No arguments required.

Open the app-owned RPC settings UI. Runtime editing is available only when the package configuration permits it.

balance

client.call('conduit', 'balance', input)

Main input: network, walletPubkey.

Read SOL balance, slot, genesis hash and observation time for the requested wallet network.

asset

client.call('conduit', 'asset', input)

Main input: network, mint.

Read and validate an original SPL mint. Returns observed decimals, supply and authorities; friendly metadata is not authenticated.

tokenAccounts

client.call('conduit', 'tokenAccounts', input)

Main input: network, walletPubkey; optional limit, from 1 to 128.

Read bounded original Token Program accounts. Truncation is reported; this is not a complete indexer.

activity

client.call('conduit', 'activity', input)

Main input: network, walletPubkey; optional before and limit.

Read cursor-paged signature activity through RPC. No continuous subscription is implied.

transaction

client.call('conduit', 'transaction', input)

Main input: network, signature; optional commitment: confirmed or finalized.

Read supported transaction bytes and RPC metadata at the requested commitment, or report that it is not yet available.

Troubleshooting

Verify your integration

Test offline, wrong genesis, a provider error, rate limits, truncated accounts and a failed settings save. Verify that a read-only UI never calls either write method. A provider timeout during submission belongs to the saved attempt's reconciliation path, not the balance refresh loop.

Integration recipes

Composition · Devnet payment · Recovery · Typed client · Schemas

Related data contracts

These schemas describe payload shape, not evidence of approval or successful execution. Match the version in your payload; older versions remain listed for compatibility.

• capp.solana-asset-observation.v1.schema.json
• capp.solana-network-observation.v1.schema.json
• capp.solana-token-accounts.v1.schema.json
• capp.solana-transaction-observation.v1.schema.json

Configuration reference

These are the selected package's configuration fields. String credential values and installation-specific defaults are never published here. A field's presence does not bypass its runtime policy.

Agent interfaces

These names are declared by the package for host/Agent integration, not JavaScript methods to invoke directly. The host must register a tool, grant its scope and enforce its approval policy. A manifest declaration alone does not prove availability in every Agent catalogue. Prefer the application API above when integrating your own app.