API Reference

The AIMS v2 API lets skills, developers, and applications interact with the AIMS marketplace, relay station, settlement engine, and on-chain attestations. All endpoints are served from https://api.aimsgateway.com/api/v2/.

Authentication

GET/api/v2/auth/nonce

Request a signable nonce for wallet authentication.

POST/api/v2/auth/native

Submit a signed nonce + wallet address to receive an AIMS JWT. Returns a Bearer token valid for session use.

POST/api/v2/auth/embedded

Authenticate via embedded wallet (same flow as native).

All authenticated requests must include Authorization: Bearer <aims_jwt>. The JWT's sub claim is the authenticated wallet address.

Developer API Keys

GET/api/v2/developer/keysAUTH

List your API keys (for skill relay access).

POST/api/v2/developer/keysAUTH

Generate a new relay API key. Pass {'tier': 'basic'|'pro'|'enterprise', 'label': '...'}.

DELETE/api/v2/developer/keys/{'{key_id}'}AUTH

Revoke an API key you own.

Relay keys use prefix aims_sk_ and are authenticated viaAuthorization: Bearer aims_sk_.... Generate keys from the API Station.

AI Relay

POST/api/v2/relay/invokeAUTH

Unified relay endpoint. Pass skill_id, tier, and input. Requires a relay API key (aims_sk_...).

POST/api/v2/relay/chat/completionsAUTH

Proxy a chat completion through AIMS relay. OpenAI-compatible request/response format.

POST/api/v2/relay/images/generationsAUTH

Proxy image generation. Requires relay API key.

POST/api/v2/relay/audio/transcriptionsAUTH

Proxy audio transcription. Requires relay API key.

POST/api/v2/relay/balance/check

Pre-flight balance check for a skill + wallet.

GET/api/v2/relay/cost/{'{skill_id}'}

Get cost estimate for a skill (paid or trial view).

Marketplace

GET/api/v2/marketplace/skills

List available skills with pagination. Query: ?page=1&page_size=20&category_id=...&tags=...&sort_by=call_count.

GET/api/v2/marketplace/skills/{'{skill_id}'}

Get a single skill's details.

GET/api/v2/marketplace/categories

List skill categories (taxonomy tree).

GET/api/v2/marketplace/skills.md

Public skill index for AI agents — returns markdown directory.

GET/api/v2/marketplace/skills/{'{skill_id}'}/skill.md

User-facing skill.md with pricing, parameters, and usage examples.

GET/api/v2/marketplace/skills/{'{skill_id}'}/dev.md

Developer-facing dev.md with full API specs and configuration.

MCP (Model Context Protocol)

POST/mcp

MCP JSON-RPC 2.0 endpoint. Methods: initialize, ping, tools/list, tools/call. Auth via Bearer token.

POST/mcp/china

China-only MCP endpoint — read-only discovery (list_llm_models, list_functional_apis). No auth required.

Developer

POST/api/v2/developer/skillAUTH

Register or update a skill. Requires Web3 signature auth.

GET/api/v2/developer/nonce

Get a nonce for Web3 signature authentication.

GET/api/v2/developer/poolsAUTH

List alliance pools for developers.

POST/api/v2/developer/resourcesAUTH

Create a developer resource.

IP Vault

GET/api/v2/ip-vault/attestationsAUTH

List your IP attestations.

POST/api/v2/ip-vault/attestationsAUTH

Register a skill for IP protection attestation.

GET/api/v2/ip-vault/badge/{'{cert_id}'}.svg

Get IP protection badge SVG for a certificate.

POST/api/v2/ip-vault/compareAUTH

Compare two attestations.

Promoter

GET/api/v2/settlement/withdraw/eligible?wallet=0x...AUTH

Check eligible withdrawal amount.

POST/api/v2/settlement/withdrawAUTH

Initiate a USDC withdrawal (min $10).

GET/api/v2/settlement/withdraw/history?wallet=0x...AUTH

List past withdrawals.

Subscription

POST/api/v2/subscription/purchaseAUTH

Purchase a subscription to a skill.

GET/api/v2/subscription/activeAUTH

List your active subscriptions.

POST/api/v2/subscription/{'{subscription_id}'}/cancelAUTH

Cancel an active subscription.