Attestra

Documentation

Build with Attestra

The SDK, the CLI, the MCP server, the contracts and the REST API. Everything here runs against NEAR testnet; one setting switches to mainnet.

Quick start

The packages are prepared for npm as @attestra/sdk, @attestra/cli and @attestra/mcp. From a clone of the repository:

terminal
pnpm install && pnpm build

# read anything, no keys needed
node packages/cli/dist/index.js schema known
node packages/cli/dist/index.js attestation fetch <uid>

# write with a testnet account from the NEAR CLI keychain
node packages/cli/dist/index.js -a you.testnet schema create \
  -d "string name, u8 level" --revocable
read.ts
import { AttestraClient } from '@attestra/sdk';

const client = new AttestraClient({ network: 'testnet' });
const r = await client.getAttestation(uid);
if (r.success) console.log(r.data.status); // active, revoked, expired...

Concepts

Schema

The fields of a claim, an optional resolver and whether it can be revoked. Its UID is deterministic.

Attestation

A claim by an attester about a subject under a schema, with expiry, revocation and a nonce.

Authority

An issuer that registered itself; governance can verify it; staking gives it a tier.

Resolver

A contract that approves or refuses attestations and revocations for schemas that name it.

Delegate

An account allowed to attest (and maybe revoke) for an authority, within a scope.

Subject

A NEAR account or a CAIP-10 account on another chain.

Statuses

pending (waiting for a resolver), active, revoking, revoked (now or by schedule) and expired. Expiry and scheduled revocation are computed on every read.

SDK

Every method returns ServiceResponse<T> (success, data, error.type, txHash) and never throws. Sign with a private key, a near-kit instance with a NEAR Connect wallet, or a key store.

signing.ts
// a key from env or the NEAR CLI keychain
new AttestraClient({ network: 'testnet', accountId: 'you.testnet', privateKey: process.env.KEY });

// a browser wallet (NEAR Connect)
import { Near, fromHotConnect } from 'near-kit';
const near = new Near({ network: 'testnet', wallet: fromHotConnect(connector) });
new AttestraClient({ network: 'testnet', accountId, near, indexerUrl });

Schemas

MethodWhat it does
registerSchema({ definition, resolver?, revocable })Register; returns the schema UID
getSchema(uid)Read a schema
listSchemas({ authority?, limit?, offset? })List (indexer, or the contract)
storeSchemaBlob(definition)Store a large definition (NEP-145)
getSchemaBlob(hash)Read a blob
registerSchemaFromBlob({ blobHash, resolver?, revocable })Register by blob hash

Attestations

MethodWhat it does
createAttestation({ schemaUid, subject, data, expirationTime?, refUid? })Attest; status created or rejected
getAttestation(uid)Read with live status
isValid(uid)Active right now?
revokeAttestation(uid)Revoke (attester only)
listAttestations({ schemaUid?, attester?, subject?, status? })List (indexer)
getNonce(account)Next attestation nonce

Authorities

MethodWhat it does
registerAuthority(metadata, kind?)Register or update
getAuthority(account)Record with tier
setAuthorityVerification(account, verified)Governance only
getProfile(account)Issued, received, schemas

Delegation

MethodWhat it does
addDelegate(delegate, scope)Grant with schemas, expiry, max uses, revoke right
removeDelegate(delegate)Remove a grant
isDelegate(authority, delegate)Active grant?
getDelegates(authority)All grants
attestOnBehalf(params)Attest as a delegate
revokeOnBehalf(uid)Revoke as a delegate
addSignerKey(publicKey)Key that may sign requests
signDelegatedAttestation(params, signer)NEP-413 request, off chain
signDelegatedRevocation(params, signer)NEP-413 revocation
submitSigned(request)Submit yourself
relaySigned(request)Relayer submits and pays

Resolvers

MethodWhat it does
whitelistAdd / whitelistRemove / whitelistCheckPer schema
feeSetFee / feeGetFee / feeDeposit / feeGetBalance / feeCollected / feeWithdraw / feeWithdrawBalanceNEAR or NEP-141
tokenGatedSetConfig / tokenGatedGetConfigMinimum NEP-141 balance
tokenRewardSetConfig / tokenRewardFund / tokenRewardGetConfig / tokenRewardGetDistributedPay subjects
pipelineSetResolvers / pipelineGetResolversChain resolvers
resolverInfo(resolver) / schemaAdmin(resolver, uid)Inspect

NEAR native

MethodWhat it does
mintCredential(uid) / getCredential(uid) / listCredentials(owner)NEP-171 credentials
scheduleRevocation(uid, at) / getScheduledRevocation(uid) / finalizeRevocation(uid)Scheduled revocation
createMultisigAuthority / proposeMultisig / approveMultisig / executeMultisig / cancelMultisig / getMultisig / getProposalk-of-n authorities
proposeDaoAttestation / proposeDaoRevocation / voteDaoProposal / getDaoProposals / getDaoPolicy / fundDaoStorage / createSputnikDaoSputnik DAO attesters
stake / unstake / getStake / getTiersStaking tiers
faucet() / tokenBalance(account)Test token
listEvents(q) / proveAttestation(uid) / proveReceipt(id, receiver)Audit trail and light client proofs

Only on NEAR

MethodWhat it does
requestPrivateCheck({ ruleId, subject, evidence })Private AI check
attestForeignEvent({ chain, txId, logIndex, log })Chain Signatures: an EVM log
attestForeignInstruction({ txId, instructionIndex, innerInstructionIndex })Chain Signatures: a Solana instruction
linkWalletMessage / linkWallet / linkedAccountWallets on other chains
registerAgent / delegateToAgent / rateAgent / getAgentProfileKnow Your Agent
grantAgentKey / revokeAgentKey / agentKeysFunction-call keys for agents
paidVerify(kind, target)x402 paid verification

For agents

agent.ts
import { getAttestraTools } from '@attestra/sdk/ai';       // LangChain
import { openAITools, runTool } from '@attestra/sdk';       // any OpenAI-compatible agent

const tools = openAITools();  // point the agent at https://cloud-api.near.ai/v1
const out = await runTool(client, 'verify_attestation', { uid });

CLI

Every command takes --json. Signing commands take -a account and read its key from ~/.near-credentials or ATTESTRA_PRIVATE_KEY.

GroupCommands
schemacreate, fetch, list, uid, known
blob (large-schema)store, fetch, register
attestationcreate, fetch, verify, list, revoke
authorityregister, fetch, verify
profile<account>
storagedeposit, balance, withdraw
delegateadd, remove, list, check, attest, revoke, add-key, keys, sign, submit
whitelistadd, remove, check, info
feeset-fee, get-fee, deposit, balance, collected, withdraw, refund
token-gatedset-config, get-config
token-rewardset-config, fund, get-config, distributed
pipeline (cross-contract)set, get
credentialmint, fetch, list
schedulerevoke, status, finalize
multisigcreate, propose-attest, propose-revoke, approve, execute, cancel, fetch, proposal
daoinfo, propose-attest, propose-membership, propose-revoke, vote, proposals, proposal, fund, create
stakingstake, unstake, info, tiers
tokenfaucet, balance
eventslist, prove, prove-receipt
checkrun, rules
chainlink-message, link, linked, attest-event
agentregister, delegate, rate, profile
payverify-claim, verify-agent
encode / decode / configoffline helpers
aiask in natural language (NEAR AI Cloud)

MCP server

Run it with one line for Claude Code, Codex or Claude Desktop, or use the hosted endpoint at /mcp on this site (read tools).

setup
# Claude Code
claude mcp add attestra -- npx -y @attestra/mcp

# Codex (~/.codex/config.toml)
[mcp_servers.attestra]
command = "npx"
args = ["-y", "@attestra/mcp"]

# write tools: set ATTESTRA_ACCOUNT_ID and ATTESTRA_PRIVATE_KEY (testnet)
ToolsKind
get_schema, list_schemas, well_known_schemas, get_attestation, verify_attestation, list_attestations, get_authority, get_delegates, get_agent_reputation, prove_attestation, linked_account, wallet_link_message, list_agent_keys, decode_data, compute_schema_uid, list_dao_proposalsread
register_schema, create_attestation, revoke_attestation, propose_dao_attestation, rate_agent, request_private_check, attest_foreign_event, attest_foreign_instruction, link_wallet, register_agent, delegate_to_agent, grant_agent_key, paid_verifywrite: capped per tool and per day, deposits and payments capped per call

Contracts

Rust, near-sdk 5.30, reproducible builds with NEP-330 metadata. Testnet accounts:

ContractAccount
schemasschemas.attestra.testnet
attestationsattestations.attestra.testnet
verdictsverdicts.attestra.testnet
credentialscredentials.attestra.testnet
stakingstaking.attestra.testnet
token (testnet)token.attestra.testnet
resolverswhitelist.attestra.testnet, fee.attestra.testnet, gated.attestra.testnet, reward.attestra.testnet, pipeline.attestra.testnet

Verify any of them from a clone: near contract verify deployed-at attestations.attestra.testnet network-config testnet now.

REST API

The indexer reads NEP-297 events from FastNEAR's transactions API and re-reads every touched record from the contracts.

EndpointReturns
GET /api/statsCounts
GET /api/statusIndexer height, chain head, lag
GET /api/schemas?authority&resolver&search&limit&offsetSchemas
GET /api/schemas/:uidOne schema with its attestation count
GET /api/attestations?schema&attester&subject&status&limit&offsetAttestations
GET /api/attestations/:uidOne attestation, decoded
GET /api/authorities?verified&kindAuthorities
GET /api/authorities/:accountOne authority with delegates
GET /api/agents, /api/agents/:accountKnow Your Agent profiles
GET /api/events?event&contract&account&uidNEP-297 audit trail
GET /api/profile/:accountIssued, received, schemas
GET /api/search?qUniversal search

Encoding and UIDs

uids
schema UID      = sha256(borsh(("attestra:schema:v1", definition, resolver: Option<AccountId>, revocable)))
attestation UID = sha256(borsh(("attestra:attestation:v1", schema_uid [32], subject, attester, data: Vec<u8>, nonce: u64)))

Data is the Borsh encoding of the fields in order. Types: bool, u8 to u128, i8 to i128, string, account_id, bytes, bytes32, and lists with [].

Only on NEAR

Private AI checks, cross-chain facts, Know Your Agent, paid verification, gasless issuing and light client proofs, each with its trust model, are described on the Only on NEAR page.

Networks

SettingTestnet
SwitchNEAR_NETWORK / NEXT_PUBLIC_NEAR_NETWORK = testnet | mainnet
RPChttps://test.rpc.fastnear.com
MPC signerv1.signer-prod.testnet
Payment token (x402)token.attestra.testnet
NEAR AI Cloudhttps://cloud-api.near.ai/v1
Explorerhttps://testnet.nearblocks.io