API Reference

This guide walks you through how the API works, how the documentation is generated, and where to find detailed references and schemas.

Rather than just listing endpoints, it explains the ecosystem around the VSL RPC API to help developers understand not only what to call, but also why and how the system behaves the way it does.

Quickstart: Querying the VSL API

You can interact with the VSL RPC server directly using JSON-RPC requests. This is especially helpful when testing or debugging without needing a full client setup.

Option 1: Querying Unsigned Endpoints with curl

The simplest way to get started is by using curl to query read-only endpoints that do not require a cryptographic signature.

For example, to check the health of your local VSL node:

curl -X POST http://localhost:44444 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "vsl_getHealth",
    "params": {}
  }'

Other common read-only endpoints include:

  • vsl_getAccountNonce

  • vsl_getBalance

  • vsl_getAssetBalances

  • vsl_listSubmittedClaimsForReceiver

All requests follow the standard JSON-RPC 2.0 specification.

Option 2: Sending Signed Requests

Many VSL operations, like making payments or submitting claims, require signed payloads for validation and security.

To send a signed request (like vsl_pay), you need to:

  1. Construct the message object (e.g. PayMessage)

  2. Encode it using RLP

  3. Sign it using EIP-191 and your Secp256k1 private key

  4. Add the signature components (r, s, v, hash) to the message

  5. Send it in a standard JSON-RPC request

Here's an example request to vsl_pay with a signed object:

curl -X POST http://localhost:44444 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "vsl_pay",
    "params": [{
      "from": "0x661403E07d8d910E45C21f3DD9303957a5D080c7",
      "to": "0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF",
      "amount": "10",
      "nonce": "100",
      "hash": "0745906a6175337c4220c921c8e0bc8dfef5e25a58ab0dfa6edc7301e99edf45",
      "r": "0xE53D9339D968314DF2EE1E7C0E661796EC25FA47F7AD92175DD318CC67B00957",
      "s": "0x583A7DD9264D63ABB4097752FCC61E601D9700E2E3170D6A55321D8E82B97A0E",
      "v": "0x01"
    }]
  }'

Signing details are explained here: Signing RPC messages — VSL SDK

Option 3: Using the Rust SDK

You can interact with the VSL RPC API directly from a Rust project using the vsl-sdk, which provides a convenient RpcWrapper for handling signed requests. This is useful when you're building integrations or tools that programmatically interact with the VSL network.

Steps

  1. Create a Rust project

cargo new send_claim --bin
cd send_claim
  1. Add dependencies

cargo add vsl-sdk --git "https://github.com/Pi-Squared-Inc/vsl-sdk"
cargo add [email protected]
cargo add [email protected] --features client
  1. Set up your main file: Replace src/main.rs with the following:

use jsonrpsee::http_client::HttpClientBuilder;
use std::str::FromStr;
use vsl_sdk::{Address, Amount, Timestamp, rpc_wrapper::RpcWrapper};

#[tokio::main(flavor = "current_thread")]
pub async fn main() {
    let http_url = "http://127.0.0.1:44444/".to_string();
    let http_client = HttpClientBuilder::new()
        .build(http_url)
        .expect("Could not connect");

    let private_key = "0xYOUR_PRIVATE_KEY".to_string();
    let mut account = RpcWrapper::from_private_key_str(&private_key, None, &http_client)
        .await
        .expect("Failed to create account wrapper");

    let claim = "Your claim".to_string();
    let claim_type = "Claim type".to_string();
    let proof = "Proof of claim".to_string();
    let verifier = Address::from_str("0xVerifierAddressHere").unwrap();
    let quorum = 1_u16;
    let fee = Amount::from_attos(1);
    let expires = Timestamp::from_seconds(Timestamp::now().seconds() + 3600);

    let response = account.submit_claim(
        claim, claim_type, proof, vec![&verifier], quorum, expires, fee
    ).await.expect("Claim submission failed");

    println!("Submitted: {:?}", response);
}
  1. Run the code: Make sure your VSL node is running at http://127.0.0.1:44444, then:

cargo run

The vsl-sdk provides higher-level abstractions like RpcWrapper, which handle message signing, formatting, and sending under the hood. You must supply a private key with enough tokens to cover any fees. See the fee schedule for details.

How the VSL API Works

The VSL API is designed around a claim-verification-settlement model.

The typical interaction begins when a client needs to assert a fact or submit a piece of data for verification. This is done through a signed SubmittedClaim, which includes metadata such as the intended verifiers, a proof, a type label for the claim, and an expiration timestamp. The claim is submitted using the vsl_submitClaim endpoint.

Once submitted, the claim is indexed and stored by VSL, making it visible to the specified verifiers. Each verifier monitors the list of submitted claims using vsl_listSubmittedClaimsForReceiver, filters claims relevant to them, and runs their own verification process externally.

If a verifier is satisfied that the claim is valid, they respond using the vsl_settleClaim endpoint, submitting a signed VerifiedClaim. This claim references the original submission and includes the verifier’s signature and address.

VSL checks the integrity of the verifier’s submission. If the referenced claim is valid, still unexpired, and if the sender is one of the designated verifiers for that claim, the verified claim is recorded. The system aggregates these verifier responses until a quorum is reached. At that point, a SettledVerifiedClaim is generated and signed by the VSL validator, serving as the canonical record of the verification outcome.

Clients or third parties can monitor the progression of claims using various query endpoints like vsl_listSettledClaimsForSender, vsl_getSettledClaimById, and so on. This allows for asynchronous processing or reactive workflows based on the final settlement status of submitted claims.

In addition to claims, the API also supports asset creation and transfers, payments, and account state management. These features use similarly signed messages, and all transactions are timestamped and tracked for verifiability.

How Fees Work

Fees in VSL are charged for all state-changing operations.

This includes not only submitting and settling claims, but also actions like sending payments, creating or transferring assets, and modifying account states. Every such operation incurs a validation fee, which is paid to the validator to compensate for transaction processing. In the case of claim submissions (vsl_submitClaim), there is an additional verification fee that gets split equally among the designated verifiers.

This fee structure is built to discourage spam, ensure accountability, and reward active participants in the verification process. Fees are denominated in the VSL token and deducted automatically when the corresponding RPC call is executed.

To view the exact fee behavior for each endpoint, refer to the fee schedule maintained in the following GitHub repository: fee-schedule.md

Endpoint Categories

Each API endpoint belongs to one of several functional categories. Here’s how the API is structured:

  • Claim verification: Submit, verify, and monitor claims (vsl_submitClaim, vsl_settleClaim, listing endpoints).

  • Payments: Transfer VSL tokens between accounts (vsl_pay, balance queries).

  • Assets: Create and manage custom tokens or assets (vsl_createAsset, vsl_transferAsset).

  • Accounts: Get balances, set or retrieve account state, manage nonces (vsl_getBalance, vsl_setAccountState, etc.).

  • Subscriptions: Receive real-time updates about claims relevant to your account.

  • Health Check: Check if the service is up (vsl_getHealth).

Each of these is documented in full in the auto-generated API documentation, including schema links and request/response formats.

Messages and Schemas

The API relies on signed message structures that encapsulate business logic:

  • SubmittedClaim: What a client sends to initiate verification.

  • VerifiedClaim: What a verifier sends after validating a claim.

  • SettledVerifiedClaim: Issued by VSL after quorum is met.

  • PayMessage, CreateAssetMessage, TransferAssetMessage, SetStateMessage: Transaction payloads for VSL’s broader system operations.

All message types conform to well-defined JSON schemas. You can inspect these schemas in the GitHub repo or generate them alongside the docs using the vsl-doc tool.

Where to Learn More

You can browse the published API reference in the vsl-sdk repository, under the docs/api subdirectory. This folder contains:

  • Descriptions of all supported RPC methods

  • JSON schemas for request and response types

  • Explanations of expected parameters and return types

This documentation is intended to help you understand how to call VSL endpoints and structure your data correctly, without needing to run or regenerate the docs yourself.

Additionally, you can find more resources here:

Last updated

Was this helpful?