Onboarding & Account Readiness

Ship an Address Inspector: accept a name or address, normalize to Bech32, check account info, balances & spendable, pending (quarantined) funds, and attributes.

Overview

Ship an Address Inspector: accept a name or address, normalize to Bech32, check account info, balances & spendable, pending (quarantined) funds, and attributes.

Success checklist:

• Name resolves → valid Bech32 address; not sanctioned.
• account_info returns; balances + spendable_balances match expectations.
• Required attributes (e.g., pio.kyc.verified) present.
• Quarantined (pending) funds endpoint returns expected items (or none).

Address Inspector

1) Normalize input, validate & sanity check

Accept flexible input (name or address) but operate on a valid Bech32 address. Operate internally on a validated Bech32 address even if users enter a name: normalize the input to a pb1… Bech32 address before any reads. For example, Users paste a name like pb:user.alice or a Bech32 address like pb1.... Normalize to a valid address before any reads.

Resolve name → address

Resolve name to address

curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "https://api.provlabs.com/provenance/name/v1/resolve/pb:user.alice"
# → { "address": "pb1..." }

SPEC →

Bech32 helpers (validate/convert) Use these helpers if you need to validate or convert address strings ↔ bytes (Bech32 encode/parse). This is useful for ensuring that user-provided input is in the correct format before making API calls.

Parse Bech32 string to bytes

# Parse string → bytes
curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "https://api.provlabs.com/cosmos/auth/v1beta1/bech32/pb1YOURADDRESS..."

SPEC →

Encode bytes to Bech32 string

# Encode bytes → string
curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "https://api.provlabs.com/cosmos/auth/v1beta1/bech32/0123ABCDEF..."

SPEC →

Sanctions check Prevent onboarding of sanctioned addresses by querying whether a specific address is sanctioned.

Check if address is sanctioned

curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "$PROV_REST_BASE/cosmos/sanction/v1beta1/check/pb1YOURADDRESS..."

SPEC →

Response shape includes a boolean sanction status; block onboarding when true.

Common Error Handling Examples

Invalid Bech32 Address Scenario: The provided address is not a valid Bech32 address. Error Code: invalid_argument Example Request:

Code snippet

curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "$PROV_REST_BASE/cosmos/auth/v1beta1/account_info/INVALID_ADDRESS"

Response:

Response

{ "code": "invalid_argument", "message": "Invalid Bech32 address format." }

How to Handle:

• Ensure the address is correctly formatted and includes the network prefix (e.g., pb1).
• Validate the address format before making the API call.

Account Not Found Scenario: The requested account does not exist. Error Code: not_found

Example Request:

Code snippet

curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "$PROV_REST_BASE/cosmos/auth/v1beta1/account_info/pb1NONEXISTENTADDRESS..."

Response:

Response

{ "code": "not_found", "message": "Account not found." }

How to handle

• Verify the account address is correct.
• Check if the account has been created or initialized on the blockchain.

2) Account snapshot (info & balances)

Confirm the account exists (or will materialize on first tx), show what it is and what it can spend now (spendable excludes vesting/escrow/locks).

Account info: presence, number, sequence (handy before signing later).

Code snippet

curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "$PROV_REST_BASE/cosmos/auth/v1beta1/account_info/pb1ADDRESS..."

SPEC →

Balances & spendable: show a wallet view; spendable gates actions like "place order."

Code snippet

# All balances (array of denoms)
curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "$PROV_REST_BASE/cosmos/bank/v1beta1/balances/pb1ADDRESS..."

# Spendable balances (what's liquid now)
curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "$PROV_REST_BASE/cosmos/bank/v1beta1/spendable_balances/pb1ADDRESS..."

# Optional: exact balance for one denom
curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "$PROV_REST_BASE/cosmos/bank/v1beta1/balances/pb1ADDRESS.../by_denom?denom=nhash"

# Optional: spendable for one denom
curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "$PROV_REST_BASE/cosmos/bank/v1beta1/spendable_balances/pb1ADDRESS.../by_denom?denom=nhash"

SPEC →

Optional: UI-Ready Address Panel (Plus) Provides a balance details snapshot (symbols, display units, pricing).

Code snippet

# Balance details snapshot (symbols, display units, pricing)
curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "$PROV_PLUS_BASE/v1/addresses/pb1ADDRESS.../balance/details"

# Address metadata (account type, labels/public name)
curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "$PROV_PLUS_BASE/v1/addresses/pb1ADDRESS.../metadata"

SPEC →

SPEC →

3) Pending Incoming Transfers (Quarantine)

Surface transfers awaiting accept/decline to prevent "missing funds" confusion.

List pending transfers to a recipient

Code snippet

curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "$PROV_REST_BASE/cosmos/quarantine/v1beta1/funds/pb1RECIPIENT..."

SPEC →

List pending transfers from specific sender → recipient (pair view)

Code snippet

curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "$PROV_REST_BASE/cosmos/quarantine/v1beta1/funds/pb1RECIPIENT.../pb1SENDER..."

SPEC →

Behavior:

• With {to_address}: pending (unaccepted & not declined) funds to that recipient.
• With {to_address}/{from_address}: pending funds for that sender→recipient pair.

Common error handling example Invalid Address

• Scenario: The provided recipient or sender address is not a valid Bech32 address.
• Error Code: invalid_argument

Example Request:

Code snippet

curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "$PROV_REST_BASE/cosmos/quarantine/v1beta1/funds/INVALID_ADDRESS"

Response:

Response

{ "code": "invalid_argument", "message": "Invalid Bech32 address format." }

How to handle

• Ensure the address is correctly formatted and includes the network prefix (e.g., pb1).
• Validate the address format before making the API call.

4) Attributes (attestations)

Enforce policy by gating access (e.g., "must have KYC"), and show verifiable labels tied to the address.

Get a specific attribute on an address

Code snippet

curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "https://api.provlabs.com/provenance/attribute/v1/attribute/pb1ADDRESS.../pio.kyc.verified"

SPEC →

List all attributes on an address

Code snippet

curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "https://api.provlabs.com/provenance/attribute/v1/attribute/pb1ADDRESS..."

SPEC →

List accounts by attribute name (allow-list)

Code snippet

curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "https://api.provlabs.com/provenance/attribute/v1/accounts/pio.kyc.verified"

SPEC →

Scan attributes by suffix (e.g., "kyc")

Code snippet

curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "https://api.provlabs.com/provenance/attribute/v1/attribute/pb1ADDRESS.../scan/kyc"

SPEC →

Pattern: For gating, check an exact attribute (first call). For discovery/audit, use accounts-by-attribute or suffix scans.

Common Error Handling Examples Attribute Not Found

• Scenario: The requested attribute does not exist on the address.
• Error Code: not_found

Example Request:

Code snippet

curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "$PROV_REST_BASE/provenance/attribute/v1/attribute/pb1ADDRESS.../nonexistent.attribute"

Response:

Response

{ "code": "not_found", "message": "Attribute not found." }

How to Handle:

• Verify the attribute name is correct.
• Check if the attribute exists on the address.

Search Account Attributes (by Suffix): no attributes found Scenario: No attributes found matching the specified suffix. Error code:

• invalid_argument: The provided suffix is invalid.
  • not_found: No attributes found matching the specified suffix.

Example

Code snippet

curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "$PROV_REST_BASE/provenance/attribute/v1/attribute/pb1ADDRESS.../scan/nonexistent_suffix"

Response:

Response

{
  "code": "not_found",
  "message": "No attributes found matching the specified suffix."
}

How to Handle:

• Verify the suffix is correct and matches existing attributes.
• Check if the address has any attributes with the specified suffix.

5) Optional: Recent transfer activity (Plus)

Useful for "proof of funds" or timelines; supports filters & cursor paging.

Code snippet

# Transfer events (filters + cursor)
curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "$PROV_PLUS_BASE/v1/asset/transfer-events?recipient=pb1ADDRESS...&denom=nhash&start_time=2025-01-01T00:00:00Z"
# → This endpoint is cursor-paged: read `next_cursor` from the response and pass `?cursor=<next_cursor>` to fetch the next page.

SPEC →

Change an Attribute (Tx) → Verify

Writes (Tx): Build the attribute tx in Vault (e.g., MsgAddAttribute, MsgDeleteAttribute) using your tenant's Vault spec → sign → broadcast via Node RPC.

Verify (reads):

Code snippet

# Specific attribute present (after Add) or absent (after Delete)
curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "$PROV_REST_BASE/provenance/attribute/v1/attribute/pb1ADDRESS.../pio.kyc.verified"

# (Optional) List all attributes on the address
curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "$PROV_REST_BASE/provenance/attribute/v1/attribute/pb1ADDRESS..."

# (Optional) Allow-list: accounts that have the attribute
curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "$PROV_REST_BASE/provenance/attribute/v1/accounts/pio.kyc.verified"

Validation & errors: Validate inputs before signing (correct msg_type_url, address formats, limits/expiration). On broadcast, Node RPC returns structured errors if a tx fails (e.g., insufficient funds, invalid message type). Surface those RPC errors in your UI.

Common Tx errors (during build/broadcast)

• Validate before signing: Bech32 addresses, msg_type_url, spend limits, expirations.
• On broadcast: Node RPC returns structured errors (e.g., insufficient funds, unauthorized, invalid message type).
• Surface RPC errors in your UI so users can fix inputs (fund granter, correct msg_type_url, adjust limit/expiration).