Vestail developer platform

Eligibility answers your product can explain.

Check what a person may own using only a declared country, residency, and asset—without sending names, IDs, or wallet addresses.

Start building Explore the API

Design-partner access

Ask Vestail for a test key. Test keys begin with vst_test_; live keys begin with vst_live_.

The mental model

One question. Four explicit steps.

01Declare
Use the buyer’s stated country and role. Vestail does not infer either.
02Resolve
Turn a company, product, or everyday phrase into a known asset class.
03Judge
Apply the country rule and preserve conditional outcomes as their own state.
04Route
Offer a venue only when the verdict allows it and required conditions are acknowledged.

Quickstart

Make your first eligibility check.

Get an API key from Vestail, keep it on your server, and send only the declared eligibility context.

1. Call the API with curl

Use the bearer key in the Authorization header. Never expose a live key in browser code.

curl

curl "$VESTAIL_API_BASE_URL/api/v1/check" \
  -H "Authorization: Bearer $VESTAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "NG",
    "residency": "citizen",
    "asset": { "class": "gold_bullion" }
  }'

2. Call it from TypeScript

Server-side TypeScript

const response = await fetch(`${process.env.VESTAIL_API_BASE_URL}/api/v1/check`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.VESTAIL_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    country: "NG",
    residency: "citizen",
    asset: { class: "gold_bullion" }
  })
});
const eligibility = await response.json();

Example response shapes

These are structural examples, not claims about a country or asset. Real reasons and sources always come from Vestail’s stored rule data.

Eligible, conditional, restricted

// Shape examples — placeholders are replaced by sourced rule data.
{ "verdict": "eligible", "reasons": ["<sourced reason>"], "conditions": [],
  "sources": [{ "label": "<source label>", "url": "<source URL>" }] }
{ "verdict": "conditional", "reasons": ["<sourced reason>"],
  "conditions": ["<condition from the rule>"],
  "sources": [{ "label": "<source label>", "url": "<source URL>" }] }
{ "verdict": "restricted", "reasons": ["<sourced reason>"], "conditions": [],
  "sources": [{ "label": "<source label>", "url": "<source URL>" }] }

Resolver

Every match shows its work.

Vestail evaluates named entities before generic aliases, so “Tesla shares” resolves to Tesla instead of the broader shares category.

1EntityNamed companies and assets

2AliasEveryday language

3CategoryGroups that fan out

4AssetCanonical asset IDs

A resolution can include a per-country rule when the same entity maps differently by location. For example, a listed company can be domestic equity in its home country and foreign equity elsewhere.

Verdict model

Three states. Never a misleading boolean.

Eligible

eligible

The sourced rules indicate ownership is available for this declared context.

Conditional

conditional · 1

A licence, cap, approval, residency rule, or other condition applies.

Restricted

restricted

The sourced rules indicate ownership is restricted for this declared context.

Routing invariant

Conditional routes require acknowledged: true. Cannot-own routes are always refused.

Unverified is not eligible

If a rule has no source, the public API returns unverified. It never promotes missing research to an eligibility verdict.

Rule engine

Country rules, issuer rules, and the stricter outcome.

Class rule

Country × buyer × asset

The baseline ownership status for the asset class.

Issuer rule

Product-specific policy

Eligibility evidence for a tokenized or issued product.

Final verdict

The stricter result wins

An unassessed product is never treated as eligible or buyable.

Rule shape

Rules are keyed by asset ID under each buyer type. Every country must contain every supported asset.

Rule JSON

{
  "status": 1,
  "sources": [],
  "verified_at": null
}

API reference

Small surface, composable responses.

All responses are JSON. Reference data is designed to be cacheable; activity data is live.

Base path/api/v1The running service publishes its generated OpenAPI 3.1 document at /api/v1/openapi.json.

POST/check

Check one asset for a declared country and residency.

POST/check/batch

Run up to 100 independent checks in one request.

GET/assets

List every class and issuer version with its profile-specific verdict.

GET/countries

Read supported countries and sourced-rule coverage.

GET/rules/{id}

Read one rule with sources and available history.

Integration guide

Use the disclosure, not a boolean.

For every response

Display the verdict, reasons, conditions, and sources together.
Treat unverified as unknown, never eligible.
Use ruleId to retrieve the current rule and available history.
Respect 429 and the Retry-After header.
Do not send personal data, IDs, or wallet addresses.

Batch request

await fetch(`${process.env.VESTAIL_API_BASE_URL}/api/v1/check/batch`, {
  method: "POST",
  headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
  body: JSON.stringify({ checks: [firstCheck, secondCheck] })
});

Trust and limits

What Vestail knows—and what it does not claim.

Buyer context is declared

Vestail does not infer citizenship, residency, or identity. Results depend on the values supplied by the buyer or integrating product.

Provenance is mandatory

A result without a source is returned as unverified, regardless of the internal rule status.

Disclosure, not enforcement

Every response includes a disclaimer. Vestail informs; it does not certify compliance or guarantee a transaction.

Usage is privacy-minimal

Vestail counts requests per API key per day for limits and future billing. Request bodies are not retained.

Residency coverage

The current rule set distinguishes citizens and foreigners. Requests for residents return unverified until resident-specific sourced rules are added.

Glossary

Know what you are—and are not—buying.

Plain-language meanings for the instrument and ownership terms used across Vestail.

Price exposure only: The product follows a reference price, but you do not own the company, index constituents, currency basket, commodity, or other underlying asset.
Underlying asset: The share, commodity, currency, index, or other reference whose value a product follows or claims to represent.
Perpetual future: A leveraged contract that tracks a reference price and has no expiry date. It is settled in money rather than by delivering the underlying.
Liquidation: The forced closing of a leveraged position when the account no longer has enough collateral to support it.
Margin and collateral: Collateral supports a trade; margin is the amount required to open and maintain a leveraged position.
Tokenised asset: An onchain token connected to an offchain asset. Its legal rights come from the issuer’s terms, not from its ticker or blockchain.
Tokenised share: A token whose issuer says a real share backs it or that it carries a claim on one. Voting, dividends, transfer, and redemption still depend on the terms.
Debt token: An issuer obligation that may follow a share’s price without making its holder a shareholder.
Custodian: An organisation that holds an underlying asset for someone else. Custody alone does not make each token holder the registered owner.
Redemption: Exchanging a product for its stated underlying asset or cash value. Eligibility checks, minimums, or jurisdiction limits may apply.
Issuer: The organisation that creates a product and defines the holder’s rights, restrictions, and claims.
Conditional: A route exists, but a licence, cap, identity check, investor-status test, or other condition may apply. Acknowledging it does not satisfy it.

Changelog

What changed.

14 October 2026

Public Eligibility API v1

Added bearer-key access, single and batch checks, profile-scoped assets, coverage statistics, rule history, unverified handling, and generated OpenAPI documentation.

9 October 2026

Developer documentation launched

Added the resolver, matrix, verdict, rule schema, route gating, provenance, API reference, and deployment-limit guidance in one connected path.