SDK & API Reference - Terminal 3 Documentation
Documentation Index
Fetch the complete documentation index at: /llms.txt
Use this file to discover all available pages before exploring further.
This page collects everything scattered across the walkthrough and tips pages into one lookup table. If you already know the name of what you’re looking for, start here before searching the guides.
Every row below is confirmed against this documentation or the OpenAPI spec. Anything only seen in community code (not in official docs) is called out separately in the last section, with a warning — not stated as fact.
ADK client SDK (@terminal3/t3n-sdk)
| Symbol | What it does | Where it’s covered |
|---|---|---|
T3nClient |
Low-level client — handles the encrypted session, SIWE auth, and execute transport. |
Set Up Development Environment |
TenantClient |
Tenant-scoped client, built around your authenticated tenantDid. |
Set Up Development Environment |
setEnvironment("testnet", "production") |
Selects which T3N cluster every client resolves its node URL from. Defaults to "production". | Quickstart |
loadWasmComponent() |
Loads the WASM component all client-side crypto runs inside. | Quickstart |
eth_get_address(key) |
Derives an Ethereum address from a key for SIWE-style auth. | Quickstart |
metamask_sign(address, _, key) |
EthSign handler — signs the login challenge. |
Quickstart |
createEthAuthInput(address) |
Builds the input for authenticate(). |
Quickstart |
client.handshake() |
Opens the encrypted session. Must be called before authenticate(). |
Quickstart |
client.authenticate(input) |
Authenticates and returns your DID — always read did.value rather than constructing it yourself. |
Quickstart |
tenant.me() |
Returns the authenticated tenant’s session info, including tenantDid. |
Set Up Development Environment |
tenant.maps.create({ tail, visibility, readers, writers }) |
Creates a tenant KV map. readers/writers default to deny — set explicitly. |
Create Tenant KV Maps |
tenant.maps.update(...) |
Updates an existing map’s ACL (e.g. to add a contractId). |
Common Errors |
map-entry-set (control-plane call) |
Seeds a value (e.g. an API key) into a KV map from outside a contract. | Seed API key into secrets map |
tenant.contracts.register({ tail, version, wasm }) |
Registers a compiled WASM contract under a tenant-local name. | Register your TEE contract |
tenant.contracts.execute(...) / executeAndDecode(...) |
Invokes a registered contract. | Invoke your contract |
agent-auth-update (contract call, signed by the data owner) |
Grants an agent access to specific functions on a specific contract, scoped to specific hosts. | Agent Auth |
getNodeUrl() |
Returns the active cluster URL for the current environment. | Set Up Development Environment |
getScriptVersion(nodeUrl, scriptName) |
Looks up the currently registered version of a script/contract. | Invoke your contract |
Naming conventions
| Pattern | Meaning |
|---|---|
z:<tid>:<tail> |
Tenant-owned KV map or contract, namespaced under your tenant ID. Never include z:<tid>: yourself — pass only the local tail. |
z:<tid>:public:<tail> |
Public (world-readable) tenant map. Never put PII here. |
{{profile.<field>}} |
Placeholder marker resolved server-side inside the enclave — the literal string is what your contract sends; the real value never enters WASM memory. |
did:t3n:<40 hex> |
An opaque, platform-assigned tenant or agent DID. Always read it back from the authenticated session — never construct or derive it. |
WIT host interfaces (contract-side capabilities)
Capabilities are determined entirely by which of these you import in world.wit — there’s no separate manifest. See Capabilities come from your WIT imports.
| Interface | Purpose | Status |
|---|---|---|
http |
Synchronous outbound HTTP. No PII allowed inline. | Available |
http-with-placeholders |
Outbound HTTP with server-resolved PII substitution. | Available |
kv-store |
Read/write tenant KV maps. | Available |
tenant (tenant-context) |
Tenant context, e.g. tenant_did(). |
Available |
logging |
In-enclave logging. | Available |
did-registry, agent-auth, user-profile, user-removal, contracts-call, authorisation, otp, config/read, provider-config, time/clock, node-config, stash, agent-registry |
Various — see Host API for the full table. | Confirmed to exist — verify current maturity before relying on one, several are still evolving |
signing, outbox, vp |
Cryptographic signing / async notifications / verifiable-presentation helpers. | Listed as coming soon as of the last docs review |
REST API
The full REST surface is documented via OpenAPI — see the API Reference tab for live, browsable endpoints generated directly from the spec (so it can’t drift out of sync with this page). Verified directly by parsing terminal-3-openapi.yml (21 paths, 24 operations, OpenAPI 3.0.3):
| Tag | Endpoints |
|---|---|
| DID V1 | GET /v1/did, POST /v1/did/register |
| OpenID Connect V1 | GET /v1/openidc/authorize, GET /v1/openidc/credentials, GET /v1/openidc/user, GET /v1/openidc/user/social_connections, POST /v1/openidc/credentials/proof, POST /v1/openidc/token |
| OpenID Connect V2 | GET /v2/openidc/user, POST /v2/openidc/token |
| Sub Client V1 | GET /v1/sub_client, GET /v1/sub_client/{subclient_id}, POST /v1/sub_client, PUT /v1/sub_client/{subclient_id}, DELETE /v1/sub_client/{subclient_id} |
| Transactional Email Template V1 | POST /v1/transactional_email_template, POST /v1/transactional_email_template/send, PUT /v1/transactional_email_template/:transactional_email_template_id |
| User V1 | POST /v1/user/create, GET /v1/user/{user_id}/social_data, GET /v1/user/{user_id}/wallet_addresses |
| VC V1 | GET /v1/vc/issuer/credentials, POST /v1/vc/issuer/credentials/proof, POST /v1/vc/issuer/store |
Auth: bearerAuth by default, with an x-api-token header required on specific endpoints (e.g. user creation). Server: https://staging.terminal3.io.
⚠️ Observed in community code only — not confirmed against official docs
The items below were reported by hackathon participants as present in the SDK’s TypeScript type definitions, but are not confirmed anywhere in this documentation. Treat the names as leads to verify against your installed SDK version’s actual types — not as a guaranteed API.
| Symbol | Where reported | Note |
|---|---|---|
buildDelegationCredential(), canonicaliseCredential(), signCredential(), buildInvocationPreimage(), signAgentInvocation() |
Multiple independent teams | Reported as a standalone delegation-credential flow, separate from the agent-auth-update grant documented in Agent Auth. If you need this, ask in the developer Telegram rather than guessing at signatures. |
DelegationCustodialClient |
One team | Reported present but unused in their integration — may be unfinished or internal. |
getAuditEvents() |
One team | Reported to exist but undocumented. |