Get the payback balance of an address

POST

https://vinu.nownodes.io/

Authorizations

ApiKeyAuthApiKeyAuth

api-key string

NOWNodes API key passed in the api-key header.

Returns the available payback balance - the fee-refund quota - of an address, in wei.

Added in the ELEMONT network upgrade of 29 August 2026.

This is the read side of the mechanism that produces the feeRefund field on transactions and receipts, and it is what makes VinuChain "feeless" for qualifying stakers. Previously there was no way to ask the node for the remaining quota; callers had to infer it from past feeRefund values.

The method lives only in the vc namespace. There is no eth_ equivalent - the rest of the vc namespace is a branding mirror of eth, but this method is unique to it.

Returns "0x0" rather than an error when the address is unknown, when the payback system is not active on the network, or when the address stakes below the minimum. A zero result is therefore not proof that the address exists.

Rate limited. The call performs up to five EVM static calls against the SFC and quota contracts (~5 x 100k gas). The node caps concurrent execution at 8 process-wide and waits at most 2 seconds for a slot; beyond that it returns JSON-RPC error code -32005 (payback RPC concurrent limit exceeded). Back off and retry rather than hammering.

Contract binding. The quota is read from QuotaContractV2 at 0x5D989A2d65d049e2198D91d8ddc31C918f2544AB, which takes effect with the 29 August rule activation. Its constructor parameters are feeRefundBlockCount=75, minStake=10 VC, quotaFactor=21000, holdTime=86400.

Body

application/json

jsonrpcstringrequired

methodstringvc_getPaybackBalancerequired

paramsArray<string | string>required

Address to query (20-byte hex, required).
Block number, block hash object, or tag (optional, defaults to latest). State resolves only for recent blocks, so a historical block parameter fails with -32000 missing trie node ... exactly as for eth_call.

Show child attributes

One of

string

idintegerrequired

Response

200OK

Available payback balance in wei

405Method Not Allowed

Method not served by this endpoint. The body is the plain-text string Method Not Allowed, not JSON.

422Unprocessable Entity

Missing API key - the api-key header was absent. The body is the plain-text string Missing API_key, not JSON.

Get the payback balance of an address

curl -X POST 'https://vinu.nownodes.io/' \
  -H 'Content-Type: application/json' \
  -H 'api-key: YOUR_API_KEY' \
  -d '{"jsonrpc": "2.0", "method": "vc_getPaybackBalance", "params": ["0x1b409ffc459802fbaa4a3797e86beb9a001b318e", "latest"], "id": 1}'

import { FetchRequest, JsonRpcProvider } from "ethers";

const request = new FetchRequest("https://vinu.nownodes.io/");
request.setHeader("api-key", "YOUR_API_KEY");

const provider = new JsonRpcProvider(request);
const result = await provider.send("vc_getPaybackBalance", ["0x1b409ffc459802fbaa4a3797e86beb9a001b318e", "latest"]);
console.log(result);

require 'eth'
require 'json'
require 'net/http'

uri = URI('https://vinu.nownodes.io/')
request = Net::HTTP::Post.new(uri)
request['Content-Type'] = 'application/json'
request['api-key'] = 'YOUR_API_KEY'
request.body = '{"jsonrpc": "2.0", "method": "vc_getPaybackBalance", "params": ["0x1b409ffc459802fbaa4a3797e86beb9a001b318e", "latest"], "id": 1}'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts JSON.parse(response.body)

from web3 import Web3

w3 = Web3(Web3.HTTPProvider(
    "https://vinu.nownodes.io/",
    request_kwargs={"headers": {"api-key": "YOUR_API_KEY"}},
))

response = w3.provider.make_request("vc_getPaybackBalance", [
    "0x1b409ffc459802fbaa4a3797e86beb9a001b318e",
    "latest",
])
print(response)

import { createPublicClient, http } from "viem";

const client = createPublicClient({
  transport: http("https://vinu.nownodes.io/", {
    fetchOptions: { headers: { "api-key": "YOUR_API_KEY" } },
  }),
});

const result = await client.request({
  method: "vc_getPaybackBalance",
  params: ["0x1b409ffc459802fbaa4a3797e86beb9a001b318e", "latest"],
});

console.log(result);

const endpoint = "https://vinu.nownodes.io/";
const apiKey = "YOUR_API_KEY";

async function nownodesRequest(payload) {
  const response = await fetch(endpoint, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "api-key": apiKey,
    },
    body: JSON.stringify(payload),
  });

  return response.json();
}

const result = await nownodesRequest({ jsonrpc: "2.0", method: "vc_getPaybackBalance", params: [
  "0x1b409ffc459802fbaa4a3797e86beb9a001b318e",
  "latest"
], id: 1 });
console.log(result);

const response = await fetch('https://vinu.nownodes.io/', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'api-key': 'YOUR_API_KEY',
  },
  body: JSON.stringify({
    "jsonrpc": "2.0",
    "method": "vc_getPaybackBalance",
    "params": [
      "0x1b409ffc459802fbaa4a3797e86beb9a001b318e",
      "latest"
    ],
    "id": 1
  }),
});

const data = await response.json();

import requests

payload = {
    "jsonrpc": "2.0",
    "method": "vc_getPaybackBalance",
    "params": [
        "0x1b409ffc459802fbaa4a3797e86beb9a001b318e",
        "latest",
    ],
    "id": 1,
}

response = requests.post(
    "https://vinu.nownodes.io/",
    json=payload,
    headers={"api-key": "YOUR_API_KEY"},
)

print(response.json())

require 'net/http'
require 'json'

uri = URI('https://vinu.nownodes.io/')
request = Net::HTTP::Post.new(uri)
request['Content-Type'] = 'application/json'
request['api-key'] = 'YOUR_API_KEY'
request.body = '{"jsonrpc": "2.0", "method": "vc_getPaybackBalance", "params": ["0x1b409ffc459802fbaa4a3797e86beb9a001b318e", "latest"], "id": 1}'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts JSON.parse(response.body)

Request Body

{
  "jsonrpc": "2.0",
  "method": "vc_getPaybackBalance",
  "params": [
    "0x1b409ffc459802fbaa4a3797e86beb9a001b318e",
    "latest"
  ],
  "id": 1
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x16345785d8a0000"
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "invalid argument"
  }
}

Method Not Allowed

Missing API_key

Documentation

How to migrate to NOWNodes

Get the payback balance of an address

Authorizations

Body

Response