Oasyce API Reference

REST API for the Oasyce L1 chain — Agent-Native Settlement Infrastructure.
Base URL: http://<node>:1317

Start Here

This page is the chain API reference. Public beta onboarding lives in the Public Beta Guide. Start there first if you want direct chain access, then come back here once your account or local signer is ready.

Chain onboarding is enough on its own. If you want local AI runtime workflows later, add oasyce-sdk: use oasyce start on the first device, oasyce join on a receiving device, and keep oasyce-agent as the lower-level data-agent surface.

If you need the native chain CLI, install it first with bash <(curl -fsSL https://raw.githubusercontent.com/Shangri-la-0428/oasyce-chain/main/scripts/install_oasyced.sh). Windows PowerShell users should use the companion install_oasyced.ps1 script instead.

If you only need an account and test tokens, use bash <(curl -fsSL https://raw.githubusercontent.com/Shangri-la-0428/oasyce-chain/main/scripts/bootstrap_public_beta_account.sh). Windows PowerShell users should use bootstrap_public_beta_account.ps1.

If you want a local node, the shortest native setup is bash <(curl -fsSL https://raw.githubusercontent.com/Shangri-la-0428/oasyce-chain/main/scripts/bootstrap_public_beta_node.sh).

If you want to run the node immediately in the current shell, use bash <(curl -fsSL https://raw.githubusercontent.com/Shangri-la-0428/oasyce-chain/main/scripts/run_public_beta_node.sh).

If you want NativeSigner from Python, install oasyce-sdk>=0.12.0 before following the SDK examples. For chain-side acceptance, prefer the adjacent oasyce-sdk main checkout in source mode. Prefer oasyce start for first-device setup and oasyce join for a receiving device. Reuse an existing local signer when possible; create a new one only on first setup.

Public Beta Guide (EN) 公测指南 (中文) Install CLI Script Install CLI Script (PowerShell) Create Account Script Create Account Script (PowerShell) Prepare Node Script Run Node Script oasyce-sdk Guide Network Overview

Quick Start

pip install oasyce-sdk

# Python
from oasyce_sdk import OasyceClient

client = OasyceClient("http://<node>:1317")
caps = client.list_capabilities()
for c in caps:
    print(f"{c.name}  {client.uoas_to_oas(c.price_per_call)} OAS/call")

# curl
curl http://<node>:1317/oasyce/capability/v1/capabilities

Authentication

Query endpoints (GET) require no authentication. Transactions require a local signer — use the oasyced tx CLI or the SDK's NativeSigner / build_* + broadcast_tx methods.

Protocol Constants

Constant	Value
Denomination	`1 OAS = 1,000,000 uoas`
Fee Split (escrow)	`90% provider · 5% protocol · 2% burn · 3% treasury`
Bonding Curve	`CW = 0.50 · tokens = supply × (√(1 + payment/reserve) − 1)`
Sell Formula	`payout = reserve × (1 − (1 − tokens/supply)²) · 95% cap`
Sell Fee	`5% protocol fee`
Access Levels	`≥0.1% → L0 · ≥1% → L1 · ≥5% → L2 · ≥10% → L3`
Block Rewards	`4→2→1→0.5 OAS/block (halving every 10M blocks)`
Burn Rate	`2% on escrow release`

Capability

Capability registry and invocation layer — register, discover, and invoke agent services.

GET/oasyce/capability/v1/capabilities

List all registered AI capabilities. Optionally filter by tag.

Parameters

Name	In	Type	Description
`tags`	query	string	Comma-separated tags to filter

curlPython

curl http://<node>:1317/oasyce/capability/v1/capabilities

# Response
{
  "capabilities": [
    {
      "capability_id": "CAP_a1b2c3",
      "name": "GPT-4 Summarizer",
      "provider": "oasyce1abc...",
      "endpoint_url": "https://api.example.com/summarize",
      "price_per_call": {"denom": "uoas", "amount": "500000"},
      "tags": ["nlp", "summarization"],
      "total_calls": "142",
      "active": true
    }
  ]
}

from oasyce_sdk import OasyceClient

client = OasyceClient()
caps = client.list_capabilities(tag="nlp")
for c in caps:
    print(f"{c.capability_id}  {c.name}  {c.price_per_call} uoas")

GET/oasyce/capability/v1/capability/{capability_id}

Get a specific capability by ID.

curlPython

curl http://<node>:1317/oasyce/capability/v1/capability/CAP_a1b2c3

cap = client.get_capability("CAP_a1b2c3")
print(f"{cap.name}  calls={cap.total_calls}  active={cap.active}")

GET/oasyce/capability/v1/capabilities/provider/{provider}

List capabilities registered by a specific provider address.

curlPython

curl http://<node>:1317/oasyce/capability/v1/capabilities/provider/oasyce1abc...

caps = client.list_capabilities(provider="oasyce1abc...")

GET/oasyce/capability/v1/earnings/{provider}

Get total earnings and call count for a provider.

curlPython

curl http://<node>:1317/oasyce/capability/v1/earnings/oasyce1abc...

# Response
{
  "provider": "oasyce1abc...",
  "total_earned": {"denom": "uoas", "amount": "15000000"},
  "total_calls": "142"
}

earnings = client.get_earnings("oasyce1abc...")
print(f"Earned: {client.uoas_to_oas(earnings.total_earned_uoas)} OAS  Calls: {earnings.total_calls}")

Datarights

Tokenized data assets with Bancor bonding curve pricing, equity-based access levels, and dispute resolution.

GET/oasyce/datarights/v1/data_asset/{asset_id}

Get data asset by ID. Returns owner, tags, share supply, reserve, and status.

curlPython

curl http://<node>:1317/oasyce/datarights/v1/data_asset/ASSET_001

# Response
{
  "data_asset": {
    "asset_id": "ASSET_001",
    "name": "NLP Training Corpus v2",
    "owner": "oasyce1abc...",
    "content_hash": "sha256:e3b0c44...",
    "tags": ["nlp", "training"],
    "total_shares": "1000",
    "reserve": {"denom": "uoas", "amount": "5000000"},
    "status": "ACTIVE",
    "version": 1
  }
}

asset = client.get_asset("ASSET_001")
print(f"{asset.name}  shares={asset.total_shares}  reserve={asset.reserve_uoas} uoas")

GET/oasyce/datarights/v1/data_assets

List all data assets. Filter by tag or owner.

Parameters

Name	In	Type	Description
`tag`	query	string	Filter by tag
`owner`	query	string	Filter by owner address

curlPython

curl "http://<node>:1317/oasyce/datarights/v1/data_assets?tag=nlp"

assets = client.list_assets(tag="nlp")
for a in assets:
    print(f"{a.asset_id}  {a.name}  status={a.status}")

GET/oasyce/datarights/v1/shares/{asset_id}

Get all shareholders and their share amounts for a data asset.

curlPython

curl http://<node>:1317/oasyce/datarights/v1/shares/ASSET_001

# Response
{
  "shareholders": [
    {"address": "oasyce1abc...", "shares": "800"},
    {"address": "oasyce1def...", "shares": "200"}
  ]
}

holders = client.get_shares("ASSET_001")
for h in holders:
    print(f"{h.address}  {h.shares} shares")

GET/oasyce/datarights/v1/dispute/{dispute_id}

Get dispute details. Includes jury votes and status.

curl

curl http://<node>:1317/oasyce/datarights/v1/dispute/DIS_001

GET/oasyce/datarights/v1/disputes

List all disputes. Optionally filter by asset.

Parameters

Name	In	Type
`asset_id`	query	string

curl

curl "http://<node>:1317/oasyce/datarights/v1/disputes?asset_id=ASSET_001"

GET/oasyce/datarights/v1/asset_children/{parent_asset_id}

Get all versioned children (forks) of a data asset.

curl

curl http://<node>:1317/oasyce/datarights/v1/asset_children/ASSET_001

GET/oasyce/datarights/v1/access_level/{asset_id}/{address}

Query access level for an address on a data asset. Returns L0-L3 based on equity share percentage.

curl

curl http://<node>:1317/oasyce/datarights/v1/access_level/ASSET_001/oasyce1abc...

# Response
{
  "access_level": "L1",
  "equity_bps": 150,
  "shares": "150",
  "total_shares": "10000"
}

# Equity thresholds: ≥0.1% → L0, ≥1% → L1, ≥5% → L2, ≥10% → L3

Settlement

Escrow-based payment settlement. Funds are locked before execution, released after verification.

GET/oasyce/settlement/v1/escrow/{escrow_id}

Get escrow by ID. Status: LOCKED → RELEASED / REFUNDED / EXPIRED.

curlPython

curl http://<node>:1317/oasyce/settlement/v1/escrow/ESC_001

# Response
{
  "escrow": {
    "escrow_id": "ESC_001",
    "creator": "oasyce1abc...",
    "provider": "oasyce1def...",
    "amount": {"denom": "uoas", "amount": "10000000"},
    "status": "LOCKED"
  }
}

escrow = client.get_escrow("ESC_001")
print(f"{escrow.escrow_id}  {escrow.status}  {client.uoas_to_oas(escrow.amount_uoas)} OAS")

GET/oasyce/settlement/v1/escrows/{creator}

List all escrows created by an address.

curlPython

curl http://<node>:1317/oasyce/settlement/v1/escrows/oasyce1abc...

escrows = client.list_escrows("oasyce1abc...")
for e in escrows:
    print(f"{e.escrow_id}  {e.status}")

GET/oasyce/settlement/v1/bonding_curve/{asset_id}

Get current bonding curve state — supply, reserve, and spot price.

curlPython

curl http://<node>:1317/oasyce/settlement/v1/bonding_curve/ASSET_001

# Response
{
  "asset_id": "ASSET_001",
  "supply": "1000",
  "reserve": {"denom": "uoas", "amount": "5000000"},
  "spot_price": {"denom": "uoas", "amount": "10000"}
}

curve = client.get_bonding_curve("ASSET_001")
print(f"Supply: {curve.supply}  Reserve: {curve.reserve_uoas} uoas  Price: {curve.spot_price_uoas} uoas")

Reputation

Time-decaying trust scores (0–500 scale, 30-day half-life). Based on invocation feedback.

GET/oasyce/reputation/v1/reputation/{address}

Get reputation score for an address.

curlPython

curl http://<node>:1317/oasyce/reputation/v1/reputation/oasyce1abc...

# Response
{
  "address": "oasyce1abc...",
  "score": 450,
  "total_feedback": 28
}

rep = client.get_reputation("oasyce1abc...")
print(f"Score: {rep.score}/500  Feedback: {rep.total_feedback}")

GET/oasyce/reputation/v1/leaderboard

Get top-rated providers sorted by score.

curlPython

curl http://<node>:1317/oasyce/reputation/v1/leaderboard

board = client.get_leaderboard()
for r in board[:10]:
    print(f"{r.address}  score={r.score}")

Work

Proof of Useful Work — distributed compute tasks with commit-reveal scheme and escrow settlement.

GET/oasyce/work/v1/task/{task_id}

Get task details including status, executor, and bounty.

curlPython

curl http://<node>:1317/oasyce/work/v1/task/TASK_001

task = client.get_task("TASK_001")
print(f"{task.task_id}  status={task.status}  bounty={task.bounty_uoas} uoas")

GET/oasyce/work/v1/tasks/status/{status}

List tasks by status. Codes: 1=SUBMITTED, 2=ASSIGNED, 3=COMMITTED, 4=REVEALING, 5=SETTLED, 6=EXPIRED, 7=DISPUTED

curlPython

curl http://<node>:1317/oasyce/work/v1/tasks/status/1  # SUBMITTED tasks

tasks = client.list_tasks(status=1)  # SUBMITTED
for t in tasks:
    print(f"{t.task_id}  {t.description[:40]}  bounty={t.bounty_uoas}")

GET/oasyce/work/v1/executors

List all registered executors with their capabilities and stats.

curlPython

curl http://<node>:1317/oasyce/work/v1/executors

executors = client.list_executors()
for e in executors:
    print(f"{e.address}  tasks_completed={e.tasks_completed}")

Onboarding

Permissionless PoW self-registration. Solve a hash puzzle to join the network and receive an airdrop (as debt).

GET/oasyce/onboarding/v1/registration/{address}

Check if an address has completed PoW registration.

curl

curl http://<node>:1317/oasyce/onboarding/v1/registration/oasyce1abc...

GET/oasyce/onboarding/v1/debt/{address}

Get outstanding airdrop debt for an address. Repaid tokens are burned.

curl

curl http://<node>:1317/oasyce/onboarding/v1/debt/oasyce1abc...

GET/oasyce/onboarding/v1/params

Get current PoW difficulty and airdrop amount (scales with total registrations).

curl

curl http://<node>:1317/oasyce/onboarding/v1/params

# Response
{
  "params": {
    "pow_difficulty": 16,
    "airdrop_amount": {"denom": "uoas", "amount": "20000000"},
    "repay_deadline_days": 90
  }
}

Bank

Standard Cosmos SDK token operations.

GET/cosmos/bank/v1beta1/balances/{address}

Get all token balances for an address.

curlPython

curl http://<node>:1317/cosmos/bank/v1beta1/balances/oasyce1abc...

# Response
{
  "balances": [
    {"denom": "uoas", "amount": "100000000"}
  ]
}

bal = client.get_balance("oasyce1abc...")
print(f"{bal.amount_oas} OAS ({bal.amount_uoas} uoas)")

GET/cosmos/base/tendermint/v1beta1/blocks/latest

Get the latest block height and time.

curlPython

curl http://<node>:1317/cosmos/base/tendermint/v1beta1/blocks/latest

block = client.get_latest_block()
print(f"Height: {block.height}  Time: {block.time}")

Transaction Examples

Transactions require signing. Use the oasyced CLI or the SDK's transaction builders.

Register a Capability

CLIPython SDK

oasyced tx oasyce_capability register \
  --name "Translation API" \
  --endpoint "https://api.example.com/translate" \
  --price 500000uoas \
  --tags "nlp,translation" \
  --from alice --chain-id oasyce-1 --yes

tx = client.build_register_capability(
    sender="oasyce1abc...",
    name="Translation API",
    endpoint="https://api.example.com/translate",
    price_uoas=500000,
    tags=["nlp", "translation"]
)
# Sign with a local signer, then:
result = client.broadcast_tx(signed_tx)

Register a Data Asset

CLIPython SDK

oasyced tx datarights register \
  --name "NLP Training Corpus v2" \
  --content-hash "sha256:e3b0c44..." \
  --tags "nlp,training" \
  --from alice --chain-id oasyce-1 --yes

tx = client.build_register_asset(
    sender="oasyce1abc...",
    name="NLP Training Corpus v2",
    content_hash="sha256:e3b0c44...",
    tags=["nlp", "training"]
)

Buy Data Shares

CLIPython SDK

oasyced tx datarights buy-shares \
  --asset-id ASSET_001 \
  --amount 10000000uoas \
  --from bob --chain-id oasyce-1 --yes

tx = client.build_buy_shares(
    sender="oasyce1def...",
    asset_id="ASSET_001",
    amount_uoas=10_000_000  # 10 OAS
)

Sell Data Shares

CLIPython SDK

oasyced tx datarights sell-shares \
  --asset-id ASSET_001 \
  --shares 50 \
  --from bob --chain-id oasyce-1 --yes

tx = client.build_sell_shares(
    sender="oasyce1def...",
    asset_id="ASSET_001",
    shares=50
)

Invoke a Capability

CLIPython SDK

oasyced tx oasyce_capability invoke \
  --capability-id CAP_a1b2c3 \
  --input '{"text":"hello world"}' \
  --from bob --chain-id oasyce-1 --yes

tx = client.build_invoke_capability(
    sender="oasyce1def...",
    capability_id="CAP_a1b2c3",
    input_data={"text": "hello world"}
)

Anchor

On-chain trace anchoring for the Thronglets P2P shared memory network. Content-addressed records with ed25519 signatures.

Get Anchor

GET/oasyce/anchor/v1/anchor/{trace_id}

Get an anchor record by trace ID (hex-encoded).

Is Anchored

GET/oasyce/anchor/v1/is_anchored/{trace_id}

Boolean check — returns whether a trace ID has been anchored on-chain.

By Capability

GET/oasyce/anchor/v1/by_capability/{capability}

List anchor records by capability string. Paginated (default limit 100).

By Node

GET/oasyce/anchor/v1/by_node/{node_pubkey}

List anchor records by node ed25519 public key (hex). Paginated.

GitHub · Discord · OpenAPI Spec · Home

Oasyce — Where agents pay agents.