VerseOS API Reference

VerseOS exposes a JSON API for registering IP records, discovering licensable rights, creating license purchases, verifying Solana payments, retrieving licenses, and reading public verification records.

Status: Private Beta / V1 pre-freeze

Base URL

Local development:

http://localhost:3000/v1

Production should use the deployed VerseOS API hostname once finalized.

Authentication

Send a VerseOS API key as a Bearer token:

Authorization: Bearer vos_live_...

API keys are server credentials. Do not expose them in browser JavaScript.

Scopes

Public IDs

VerseOS uses readable public IDs for resources:

Use public IDs in integrations whenever the endpoint supports them.

Assets

GET /v1/assets

Discover publicly visible VerseOS assets.

Scope: assets:read

Public discovery includes assets whose verification_status is:

• claimed
• under_review
• verified

Query parameters

Example

curl "http://localhost:3000/v1/assets?verification_status=verified&licensable=true" \
  -H "Authorization: Bearer $VERSEOS_API_KEY"

List response

{
  "object": "list",
  "data": [
    {
      "public_id": "VRS-C9A739A09131",
      "name": "Puzzle Caspius",
      "type": "character",
      "verification_status": "verified"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 3,
    "total_pages": 1,
    "has_more": false
  }
}

POST /v1/assets

Register an asset under the API-key owner.

Scope: assets:write

The exact writable field set remains pre-freeze. Treat the current SDK type as the source of truth until V1 is formally frozen.

GET /v1/assets/:id

Read one asset record.

Scope: assets:read

Current V1 behavior is owner-oriented. Do not use this route as public discovery; use GET /v1/assets, GET /v1/assets/:id/rights, or GET /v1/verify/:id for public records.

GET /v1/assets/:id/rights

Return all currently available license offers for one publicly visible asset.

Scope: rights:read

Accepts a VRS-... public ID and, during private beta, may also accept an internal UUID.

curl "http://localhost:3000/v1/assets/VRS-C9A739A09131/rights" \
  -H "Authorization: Bearer $VERSEOS_API_KEY"

Rights

GET /v1/rights

Search the available rights catalog across publicly visible assets.

Scope: rights:read

Only rights with status = available are returned.

Query parameters

Example

curl "http://localhost:3000/v1/rights?medium=game&max_price_usdc=1000" \
  -H "Authorization: Bearer $VERSEOS_API_KEY"

Example right

{
  "object": "right",
  "public_id": "RGT-794B30A19A22",
  "medium": "game",
  "territory": "Worldwide",
  "duration_months": 12,
  "exclusivity": "nonexclusive",
  "royalty_bps": 500,
  "price_minor": 100,
  "price_usdc": "1.00",
  "currency": "USDC",
  "status": "available",
  "ai_usage": "not_allowed",
  "derivative_works": "not_allowed",
  "asset": {
    "public_id": "VRS-C9A739A09131",
    "name": "Puzzle Caspius",
    "type": "character",
    "verification_status": "verified"
  }
}

GET /v1/rights/:id

Read one available right.

Scope: rights:read

curl "http://localhost:3000/v1/rights/RGT-794B30A19A22" \
  -H "Authorization: Bearer $VERSEOS_API_KEY"

Standard license checkout

POST /v1/license-intents

Create a pending license purchase intent.

Scope: licenses:write

Request

{
  "right_id": "RGT-794B30A19A22"
}

Example

curl -X POST "http://localhost:3000/v1/license-intents" \
  -H "Authorization: Bearer $VERSEOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"right_id":"RGT-794B30A19A22"}'

Payment split

The current standard checkout snapshots a two-recipient USDC split:

• creator: 97.5%
• VerseOS platform fee: 2.5%

A response includes payment destinations and exact base-unit amounts. Treat token base-unit fields as strings.

{
  "object": "license_intent",
  "public_id": "INT-...",
  "status": "pending",
  "right_id": "RGT-794B30A19A22",
  "asset_id": "VRS-C9A739A09131",
  "amount_minor": 100,
  "amount_usdc": "1.00",
  "currency": "USDC",
  "payment": {
    "network": "devnet",
    "recipient_wallet": "CREATOR_WALLET",
    "platform_fee_wallet": "VERSEOS_FEE_WALLET",
    "creator_amount_base_units": "975000",
    "platform_fee_base_units": "25000",
    "platform_fee_bps": 250
  }
}

POST /v1/payments/verify

Verify a confirmed Solana payment and issue the license.

Scope: licenses:write

Request

{
  "signature": "SOLANA_TRANSACTION_SIGNATURE",
  "license_intent_id": "INT-..."
}

VerseOS verifies:

1. the intent belongs to the API-key user;
2. the Solana transaction is confirmed and successful;
3. the configured USDC mint is used;
4. the exact creator transfer is present;
5. the exact 2.5% platform-fee transfer is present;
6. the transaction signature has not been replayed.

On success VerseOS records the payment, issues LIC-..., and fulfills the intent.

Licenses

GET /v1/licenses/:id

Read one license owned by the API-key user as licensor or licensee.

Scope: licenses:read

curl "http://localhost:3000/v1/licenses/LIC-7320640BC86A" \
  -H "Authorization: Bearer $VERSEOS_API_KEY"

Private-beta note: some current responses still expose internal UUIDs and plural relation keys such as assets / rights. Those are implementation details and should not be treated as long-term V1 contract guarantees.

Verification / Rights Passport

GET /v1/verify/:id

Read a public Rights Passport-style verification record.

Scope: verify:read

curl "http://localhost:3000/v1/verify/VRS-C9A739A09131" \
  -H "Authorization: Bearer $VERSEOS_API_KEY"

A verification record can include:

• asset metadata;
• claim verification status;
• evidence hashes;
• provenance attestations;
• available rights.

Important: VerseOS verification represents the status of a claim within VerseOS. It is not a legal determination of copyright ownership.

A provenance attestation establishes evidence integrity, timestamping, and wallet association. It does not independently prove legal ownership.

x402 agent licensing

POST /v1/agent-licenses

Allow an API-key authenticated agent to buy a VerseOS license through x402 v2 on Solana.

Scope: licenses:write

Required headers

Authorization: Bearer vos_live_...
Content-Type: application/json
Idempotency-Key: unique-purchase-id

Request

{
  "right_id": "RGT-794B30A19A22"
}

First response

If no payment is attached, VerseOS returns:

402 Payment Required
PAYMENT-REQUIRED: <base64 x402 v2 challenge>

The challenge binds the price, network, token asset, creator payTo wallet, and quote terms.

Successful response

{
  "object": "agent_license",
  "x402": true,
  "quote_id": "XQ-A9B77CB8E9D7",
  "payment": {
    "status": "settled",
    "network": "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
    "transaction": "SOLANA_SIGNATURE"
  },
  "license": {
    "public_id": "LIC-F40BD43BF6BC",
    "status": "active",
    "starts_at": "2026-08-13T16:55:40.501+00:00",
    "ends_at": "2027-08-13T16:55:40.501+00:00"
  },
  "already_fulfilled": false
}

The response also exposes:

PAYMENT-RESPONSE: <base64 settlement response>

Current x402 fee policy

The devnet x402 MVP sends the full license price directly to the creator. It does not collect the normal VerseOS 2.5% platform fee because the standard x402 exact requirement has a single payTo recipient.

Mainnet should remain disabled until VerseOS chooses a production x402 fee/payout strategy.

Errors

API errors use an error code/message envelope through the VerseOS API helper.

Typical HTTP statuses:

Rate limits

Developer API keys have a configured per-minute rate limit. VerseOS records usage and exposes rate-limit headers on API responses.

V1 pre-freeze notes

Before declaring V1 frozen, VerseOS should still normalize:

• public IDs as the canonical external identifiers;
• singular asset / right relation names;
• token base-unit amounts as strings;
• error envelope shape across every route;
• POST idempotency for non-x402 write endpoints;
• atomic/recoverable standard payment fulfillment.