API / Integration

DRAFT — nothing on this page is live

The Arc Data Network is not deployed. No endpoint below accepts requests, no API key can be issued, and every path, field name, and response shape is a proposal that will change. This page exists so integrators can review the intended shape and tell us what is wrong with it before it is built. Do not write production code against it.

What the Data Network is for

The Data Network is the layer that lets wallets, exchanges, lending markets, portfolio applications, and AI agents consume Arc Trace data directly, rather than through the Explorer or Terminal UI.

The four intended surfaces:

Surface	Question it answers
Asset lookup	Is this contract canonical, wrapped, bridged, synthetic, or fraudulent?
Asset Passport	Who issued it, what legal claim does it carry, how is it backed?
Risk feed	What are this asset's material risks, and how have they changed?
Corporate actions	What is about to happen to the underlying instrument?

Proposed authentication

Access is expected to be tied to the Arc Access Pass held by a wallet, exchanged for a short-lived bearer token. API allowances are recorded in the pass itself, so tier and rate limit derive from onchain entitlement rather than a separate billing system.

TS

// PROPOSED — not live
const res = await fetch("https://api.arctrace.xyz/v1/auth/session", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    address: "0xYourWallet",
    signature,   // EIP-191 signature over the issued challenge
    challenge,
  }),
});

const { token, expiresAt, tier } = await res.json();

Rate limits, quota accounting, and enterprise key issuance are undecided.

Proposed endpoints

Asset lookup

HTTP

GET /v1/assets/{chainId}/{address}

TS

// PROPOSED — not live
type AssetResponse = {
  chainId: number;
  address: `0x${string}`;
  symbol: string;
  canonical: boolean;
  representation: "canonical" | "wrapped" | "bridged" | "synthetic" | "unverified";
  issuer: { name: string; verified: boolean; bondPosted: boolean } | null;
  passportId: string | null;
  warnings: Array<{ code: string; severity: "info" | "warning" | "danger"; message: string }>;
};

The representation and warnings fields are the point of this endpoint. A wallet integrating Arc Trace should be able to show a user "this is not the canonical contract" before a swap is signed.

Asset Passport

HTTP

GET /v1/passports/{passportId}

Returns the six Passport fields described in Protocol Mechanics as structured data, each with its own provenance and last-verified timestamp. Field-level provenance matters more than the values: an integrator needs to know whether a backing claim was attested by a staked verifier or merely scraped from an issuer page.

Risk feed

HTTP

GET /v1/risk/{chainId}/{address}

Returns per-dimension scores rather than a single number, plus the methodology version used. Consumers should render the dimensions, not just the aggregate.

TS

// PROPOSED — not live
type RiskResponse = {
  methodologyVersion: string;
  dimensions: Record<
    "issuer" | "legalStructure" | "oracle" | "liquidity" |
    "smartContract" | "backingVerification" | "transferRestrictions" | "bridgeExposure",
    { score: number; weight: number; rationale: string }
  >;
};

Scores are not safety ratings

A risk score describes visible, comparable risk dimensions under a published methodology. It is not a certification, a recommendation, or a statement that an asset is safe. Any integration that renders a Arc Trace score as a green checkmark is misrepresenting it.

Corporate-action webhooks

TS

// PROPOSED — not live
type CorporateActionEvent = {
  eventId: string;
  type:
    | "distribution" | "split" | "reverse_split" | "merger" | "acquisition"
    | "spin_off" | "rights_issue" | "symbol_change" | "buyback"
    | "suspension" | "delisting" | "market_closure";
  effectiveAt: string;          // ISO 8601
  underlyingSymbol: string;
  affectedTokens: Array<{ chainId: number; address: `0x${string}` }>;
  issuerTreatment: string | null;  // how this issuer states it will handle the event
  confirmed: boolean;
};

Delivery would be signed webhook POSTs with replay protection. The issuerTreatment field is deliberately nullable — different issuers handle the same corporate action differently, and an unknown treatment must be representable rather than guessed.

Open questions we want integrator input on

1. Should risk data be pull-only, or is a streaming subscription needed for liquidation-sensitive consumers such as lending markets?
2. Is field-level provenance on the Passport worth the response size, or should it sit behind a separate call?
3. How should an asset that has no verified issuer be represented — omitted, or returned with an explicit unverified marker?
4. What latency guarantee would a lending market need on a suspension or delisting event for it to be actionable?

Contact details for feedback are on the Links page.