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
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:
Construct the message object (e.g.
PayMessage
)Encode it using RLP
Sign it using EIP-191 and your Secp256k1 private key
Add the signature components (
r
,s
,v
,hash
) to the messageSend 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
Create a Rust project
cargo new send_claim --bin
cd send_claim
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
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);
}
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:
Explore the endpoint reference: API Docs Folder
Understand the system flow: flow.md
Check the endpoint fees: fee-schedule.md
Last updated
Was this helpful?