Get Started
NUVA Labs' APIs make it simple to build on Provenance Blockchain, enabling you to tokenize assets, manage permissions, execute trades and manage confidential data with ease. This page gets you set up fast: authenticate, declare bases, make your first call, pick a write path, and verify fee-payer readiness. Full how-to recipes live in the workflow hubs (Identity & Access, Tokenization, Trades & Settlement).
What you'll need
- Tenant credentials to obtain a bearer token.
- A Bech32 address to query (tp1… testnet / pb1… mainnet).
Authentication
All operations in the API reference require bearerAuth. Use your tenant credentials to obtain a bearer token. If you don't have access yet, contact inbound@nuvalabs.com.
Use these headers on every call:
| Header | Value |
|---|---|
| Authorization | Bearer <TOKEN> |
| Content-Type | application/json |
Base URLs (declare once)
Declare these base URLs in your environment so snippets are portable and consistent with the rest of the docs:
# .env or shell exports (example)
export PROV_REST_BASE="https://api.provlabs.com" # Reads & writes (standard base)
export PROV_PLUS_BASE="https://api.provlabs.com" # Plus aggregates live under /v1/...
export PROV_VAULT_BASE="https://api.provlabs.com/vault" # Alternate mirror for same writes
export PROV_API_TOKEN="YOUR_BEARER_TOKEN"
You'll see both the standard base and /vault mirror on operation pages in the API reference.
Networks (Node RPC):
- Mainnet RPC: https://pio-mainnet-1-rpc.provlabs.com
- Testnet RPC: https://pio-testnet-1-rpc.test.provlabs.com (Used only if you take the advanced Vault+RPC path.)
Making your first call
A quick, safe way to confirm your token and connectivity is to fetch account balances:
curl -s -H "Authorization: Bearer $PROV_API_TOKEN" \
"$PROV_REST_BASE/cosmos/bank/v1beta1/balances/{address}"
Replace {address} with a valid Bech32 address. A successful response confirms your token is valid.
Optional) Transfer events for a quick UI table sanity check:
curl -s -H "Authorization: Bearer $PROV_API_TOKEN" \
"$PROV_PLUS_BASE/v1/asset/transfer-events?recipient={address}"
# Optional: &sender=... &denom=... &before=... &after=... &limit=... &cursor=...
Two write paths (at a glance)
You can perform writes either with first-class direct POST operations (recommended) or by building and broadcasting signed transactions (advanced). Both patterns are documented:
-
Direct POST (recommended): Call documented POST/PATCH operations on https://api.provlabs.com/.... This is the default path surfaced across the API reference and all workflow hubs.
-
Advanced (Vault + RPC): Build an unsigned tx with Vault, sign (service key/HSM/wallet), then broadcast via Node RPC. Use this when you need custom signing flows.
Guidance: Use Direct POST unless you specifically need manual signing/broadcast control. It's simpler, fully supported in the API reference, and aligns with the workflow guides.
Fee-payer readiness (critical before your first write)
Provenance charges network fees in nhash (the base/fee token). Choose a model and verify the fee-payer:
- Caller pays: the calling address must have spendable nhash.
- Sponsor pays (recommended UX) → create a fee-grant from a funded granter to the grantee (caller).
Pick a fee model and verify the fee-payer can pay network fees:
Check spendable balances (all denoms)
curl -s -H "Authorization: Bearer $PROV_API_TOKEN" \
"$PROV_REST_BASE/cosmos/bank/v1beta1/spendable_balances/{address}"
Spendable nhash (by denom)
curl -s -H "Authorization: Bearer $PROV_API_TOKEN" \
"$PROV_REST_BASE/cosmos/bank/v1beta1/spendable_balances/{address}/by_denom?denom=nhash"
Check fee-grant (specific granter → grantee)
curl -s -H "Authorization: Bearer $PROV_API_TOKEN" \
"$PROV_REST_BASE/cosmos/feegrant/v1beta1/allowance/{granter}/{grantee}"
If there's no spendable nhash and no fee-grant, fund the fee-payer or create a fee-grant (see Identity & Access → Authorization Grants).
Common errors & quick fixes
| Symptom / message | Likely cause | Confirm with… | Fix |
|---|---|---|---|
| insufficient funds / insufficient fees | Fee-payer has no spendable nhash and no grant | Spendable reads; fee-grant read | Fund fee-payer or create fee-grant |
| missing required attribute (restricted marker) | Sender/recipient lacks a required attribute | Marker required_attributes; account attributes | Add attribute(s) or use eligible address |
| not authorized: ACCESS_* | Caller lacks marker permission (mint/admin/etc.) | Marker access control read | Grant required ACCESS_* |
| invalid bech32 | Malformed address | Visual check of prefix (tp1… testnet / pb1… mainnet) | Use a valid Bech32 address |
Glossary (quick orientation)
Before diving into the APIs, familiarize yourself with these key concepts:
Markers (Fungible Tokens) Markers are fungible tokens on Provenance Blockchain, representing interchangeable units of value (e.g., stablecoins, utility tokens). Types:
- MARKER_TYPE_COIN: Standard fungible tokens with unrestricted transfers.
- MARKER_TYPE_RESTRICTED: Permissioned tokens requiring attributes or permissions for transfers.
Scopes (Non-Fungible Assets) Scopes are structured containers for unique assets and their on-chain records. Components:
- Scope Specification: Defines the structure and purpose of a scope.
- Value Owner: The address registered as the owner of the scope's value.
nhash Provenance's base/fee token used to pay network fees.
Denom A Denom is atToken identifier (e.g., nhash). Fee-grant Sponsor-pays model: granter gives grantee an allowance to pay fees. Plus endpoints Curated, UI-ready aggregates for balances, metadata, transfers, NAV, holders, etc.
- Base URL: /v1/... Net Asset Value (NAV) NAV represents the value of an asset, used for investor reporting and dashboards. Data access Addresses allowed to access off-chain data linked to a scope. Value owner Address registered as the scope's value owner; can be updated/transferred.
Where to go next
Onboarding & Accounts Hub → Onboarding & account readiness, attributes, permissions and multisig governance. Build address inspectors, verify spendable funds, and implement sponsor-pays flows.
Tokenization Hub → Mint, transfer & manage digital assets
- Mint & manage Markers (Fungible Tokens): Create Token, Transfer Tokens, supply/holders/NAV.
- Create & issue Scopes (Non-Fungible): Create Scope, Add Data Access, Update Value Owner, ownership/NAV reads.
Unified API Reference → Canonical source for every operation and endpoint used across Accounts, Digital Assets, Settlement, Block Vault, etc.