Self Enterprise

https://docs.self.xyz
Admin
Self is a privacy-first, open-source identity protocol built on zero-knowledge proofs. Self...
Tokens:62,752
Snippets:749
Trust Score:8.3
Update:4 months ago
Show doc for...
Tokens:
Raw
### Webhook Request Example

Source: https://docs.self.xyz/get-started/concepts

Demonstrates how to make a GET request to query documentation, including an example of a GET request with an 'ask' query parameter.

```http
GET https://docs.self.xyz/get-started/concepts.md?ask=<question>
```

--------------------------------

### Example GET Request with 'ask' Parameter

Source: https://docs.self.xyz/reference/troubleshooting

Illustrates how to query the documentation dynamically by appending an 'ask' parameter to the GET request URL. This is useful for retrieving specific information or clarifications not explicitly present on the page.

```http
GET https://docs.self.xyz/reference/troubleshooting.md?ask=<question>
```

--------------------------------

### API Request Example

Source: https://docs.self.xyz/verification-flows/test-vs-live

Demonstrates how to make an API request to the Self platform. This example shows a GET request to a specific documentation URL with an 'ask' query parameter for dynamic querying.

```http
GET https://docs.self.xyz/verification-flows/test-vs-live.md?ask=<question>
```

--------------------------------

### Install yarn package

Source: https://docs.self.xyz/sdk/nodejs

Install the SDK using yarn.

```bash
yarn add @selfxyz/enterprise-sdk
```

--------------------------------

### API Request Example

Source: https://docs.self.xyz/get-started/what-is-self-enterprise

Demonstrates how to make a GET request to the documentation API with an 'ask' parameter to query the documentation.

```http
GET https://docs.self.xyz/get-started/what-is-self-enterprise.md?ask=<question>
```

--------------------------------

### Install Self.xyz Enterprise SDK

Source: https://docs.self.xyz/get-started/quickstart

Install the Node.js SDK using npm. Ensure you have Node.js 20+.

```bash
npm install @selfxyz/enterprise-sdk
```

--------------------------------

### Install pnpm package

Source: https://docs.self.xyz/sdk/nodejs

Install the SDK using pnpm.

```bash
pnpm add @selfxyz/enterprise-sdk
```

--------------------------------

### Install Python SDK

Source: https://docs.self.xyz/self-agent-id/agent-builder

Install the Self Agent ID SDK for Python using pip.

```bash
pip install selfxyz-agent-sdk
```

--------------------------------

### Complete Registration Example

Source: https://docs.self.xyz/self-connect/developer-guide

This example demonstrates the full process of registering an attestation as an issuer. It includes setting up authentication, checking and topping up ODIS quota, obtaining an obfuscated identifier, and finally registering the attestation on-chain. Ensure you have the necessary private key and addresses configured.

```typescript
import {
  createWalletClient,
  createPublicClient,
  http,
  parseEther,
  type Address,
  type Hex
} from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { celoAlfajores } from "viem/chains";
import { OdisUtils } from "@celo/identity";
import { OdisContextName } from "@celo/identity/lib/odis/query";
import type { AuthSigner } from "@celo/identity/lib/odis/query";
import { getContract } from "viem";
import { federatedAttestationsABI, odisPaymentsABI, stableTokenABI } from "@celo/abis";

// Configuration
const ISSUER_PRIVATE_KEY = process.env.ISSUER_PRIVATE_KEY as Hex;
const FEDERATED_ATTESTATIONS_ADDRESS = "0x70F9314aF173c246669cFb0EEe79F9Cfd9C34ee3" as Address;
const ODIS_PAYMENTS_ADDRESS = "0x645170cdB6B5c1bc80847bb728dBa56C50a20a49" as Address;
const STABLE_TOKEN_ADDRESS = "0x874069Fa1Eb16D44d622F2e0Ca25eeA172369bC1" as Address;

// Setup
const account = privateKeyToAccount(ISSUER_PRIVATE_KEY);
const walletClient = createWalletClient({
  account,
  transport: http(),
  chain: celoAlfajores
});

const publicClient = createPublicClient({
  transport: http(),
  chain: celoAlfajores
});

const issuerAddress = account.address;

// User information (provided by user after verification)
const userPlaintextIdentifier = "+12345678910";
const userAccountAddress = "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb" as Address;
const attestationVerifiedTime = BigInt(Math.floor(Date.now() / 1000));

async function registerAttestation() {
  // 1. Setup authentication
  const authSigner: AuthSigner = {
    authenticationMethod: OdisUtils.Query.AuthenticationMethod.WALLET_KEY,
    sign191: ({ message, account }) => 
      walletClient.signMessage({ message, account })
  };

  const serviceContext = OdisUtils.Query.getServiceContext(
    OdisContextName.ALFAJORES
  );

  // 2. Check and top up ODIS quota if needed
  const { remainingQuota } = await OdisUtils.Quota.getPnpQuotaStatus(
    issuerAddress,
    authSigner,
    serviceContext
  );

  console.log("Remaining quota:", remainingQuota);

  if (remainingQuota < 1) {
    console.log("Purchasing ODIS quota...");
    
    // Get contract instances
    const stableToken = getContract({
      address: STABLE_TOKEN_ADDRESS,
      abi: stableTokenABI,
      client: { public: publicClient, wallet: walletClient }
    });
    
    const odisPayments = getContract({
      address: ODIS_PAYMENTS_ADDRESS,
      abi: odisPaymentsABI,
      client: { public: publicClient, wallet: walletClient }
    });
    
    const ONE_CENT_CUSD = parseEther("0.01");
    
    // Approve ODIS Payments to spend cUSD
    const approveHash = await stableToken.write.approve([
      ODIS_PAYMENTS_ADDRESS,
      ONE_CENT_CUSD
    ]);
    await publicClient.waitForTransactionReceipt({ hash: approveHash });
    
    // Pay for quota
    const paymentHash = await odisPayments.write.payInCUSD([
      issuerAddress,
      ONE_CENT_CUSD
    ]);
    await publicClient.waitForTransactionReceipt({ hash: paymentHash });
    
    console.log("ODIS quota purchased successfully");
  }

  // 3. Get obfuscated identifier from ODIS
  console.log("Getting obfuscated identifier...");
  const { obfuscatedIdentifier } = await OdisUtils.Identifier.getObfuscatedIdentifier(
    userPlaintextIdentifier,
    OdisUtils.Identifier.IdentifierPrefix.PHONE_NUMBER,
    issuerAddress,
    authSigner,
    serviceContext
  );

  console.log("Obfuscated Identifier:", obfuscatedIdentifier);

  // 4. Register attestation on-chain
  console.log("Registering attestation...");
  const federatedAttestations = getContract({
    address: FEDERATED_ATTESTATIONS_ADDRESS,
    abi: federatedAttestationsABI,
    client: { public: publicClient, wallet: walletClient }
  });

  const hash = await federatedAttestations.write.registerAttestationAsIssuer([
    obfuscatedIdentifier as Hex,
    userAccountAddress,
    attestationVerifiedTime
  ]);

  const receipt = await publicClient.waitForTransactionReceipt({ hash });
  
  console.log("Attestation registered!");
  console.log("Transaction:", receipt.transactionHash);
  
  return {
    obfuscatedIdentifier,
    transactionHash: receipt.transactionHash
  };
}

// Execute
registerAttestation().catch(console.error);

```

--------------------------------

### Install Rust SDK

Source: https://docs.self.xyz/self-agent-id/agent-builder

Install the Self Agent ID SDK for Rust using cargo.

```bash
cargo add self-agent-sdk
```

--------------------------------

### Registration Session Example Response

Source: https://docs.self.xyz/self-agent-id/rest-api

Example response from creating a registration session, including session token, deep link, QR data, agent address, mode, and network.

```json
{
  "sessionToken": "enc_...",
  "deepLink": "selfapp://verify?scope=...",
  "qrData": "selfapp://verify?scope=...",
  "agentAddress": "0x83fa...ff00",
  "mode": "linked",
  "network": "mainnet"
}
```

--------------------------------

### Install Self Agent SDK

Source: https://docs.self.xyz/self-agent-id/agent-builder/service-operator

Install the Self Agent SDK for TypeScript, Python, or Rust using their respective package managers.

```bash
npm install @selfxyz/agent-sdk    # TypeScript
pip install selfxyz-agent-sdk      # Python
cargo add self-agent-sdk           # Rust
```

--------------------------------

### Install Self Connect Packages

Source: https://docs.self.xyz/self-connect/developer-guide

Install the necessary npm packages for Self Connect integration. This includes the identity package, contract ABIs, and the Viem library.

```bash
npm install @celo/identity @celo/abis viem
```

--------------------------------

### Install TypeScript SDK

Source: https://docs.self.xyz/self-agent-id/agent-builder

Install the Self Agent ID SDK for TypeScript using npm.

```bash
npm install @selfxyz/agent-sdk
```

--------------------------------

### Complete Identifier Lookup Example

Source: https://docs.self.xyz/self-connect/developer-guide

Performs a complete lookup of an identifier, including setting up authentication, getting the obfuscated identifier, querying FederatedAttestations, and processing the results. Requires specific imports and setup for Viem and Celo identity services.

```typescript
import { createPublicClient, http, type Address, type Hex } from "viem";
import { celoAlfajores } from "viem/chains";
import { OdisUtils } from "@celo/identity";
import { OdisContextName } from "@celo/identity/lib/odis/query";
import { getContract } from "viem";
import { federatedAttestationsABI } from "@celo/abis";

const FEDERATED_ATTESTATIONS_ADDRESS = "0x70F9314aF173c246669cFb0EEe79F9Cfd9C34ee3" as Address;

const publicClient = createPublicClient({
  transport: http(),
  chain: celoAlfajores
});

async function lookupIdentifier(
  plaintextIdentifier: string,
  identifierType: string,
  trustedIssuers: Address[]
): Promise<Address[]> {
  // 1. Setup authentication for lookup
  // For read-only operations, use a zero address
  const lookupAddress = "0x0000000000000000000000000000000000000000" as Address;
  
  const authSigner = {
    authenticationMethod: OdisUtils.Query.AuthenticationMethod.WALLET_KEY,
    sign191: async () => "0x" as Hex
  };

  const serviceContext = OdisUtils.Query.getServiceContext(
    OdisContextName.ALFAJORES
  );

  // 2. Get obfuscated identifier
  const { obfuscatedIdentifier } = await OdisUtils.Identifier.getObfuscatedIdentifier(
    plaintextIdentifier,
    identifierType,
    lookupAddress,
    authSigner,
    serviceContext
  );

  console.log("Looking up:", obfuscatedIdentifier);

  // 3. Query FederatedAttestations
  const federatedAttestations = getContract({
    address: FEDERATED_ATTESTATIONS_ADDRESS,
    abi: federatedAttestationsABI,
    client: publicClient
  });

  const attestations = await federatedAttestations.read.lookupAttestations([
    obfuscatedIdentifier as Hex,
    trustedIssuers
  ]);

  const [countsPerIssuer, accounts, signers, issuedOns, publishedOns] = attestations;

  // 4. Process results
  console.log("Found attestations:");
  
  let accountIndex = 0;
  for (let i = 0; i < trustedIssuers.length; i++) {
    const count = Number(countsPerIssuer[i]);
    console.log(`\nIssuer: ${trustedIssuers[i]}`);
    console.log(`Attestation count: ${count}`);
    
    for (let j = 0; j < count; j++) {
      console.log(`  Account: ${accounts[accountIndex]}`);
      console.log(`  Signer: ${signers[accountIndex]}`);
      console.log(`  Issued: ${new Date(Number(issuedOns[accountIndex]) * 1000).toISOString()}`);
      console.log(`  Published: ${new Date(Number(publishedOns[accountIndex]) * 1000).toISOString()}`);
      accountIndex++;
    }
  }

  return accounts as Address[];
}

// Example usage
const trustedIssuers: Address[] = [
  "0x6549aF2688e07907C1b821cA44d6d65872737f05", // Kaala
  "0x388612590F8cC6577F19c9b61811475Aa432CB44"  // Libera
];

lookupIdentifier(
  "+12345678910",
  OdisUtils.Identifier.IdentifierPrefix.PHONE_NUMBER,
  trustedIssuers
).catch(console.error);
```

--------------------------------

### Install Self Agent ID CLI (Python)

Source: https://docs.self.xyz/self-agent-id/cli

Install the Self Agent ID SDK using pip and then invoke the CLI.

```bash
pip install selfxyz-agent-sdk
# Then use:
self-agent register init ...
```

--------------------------------

### Session Schema (v1) Example

Source: https://docs.self.xyz/self-agent-id/cli

An example of the JSON structure for a session file, detailing version, mode, network, addresses, session ID, handoff URL, and status.

```json
{
  "version": 1,
  "mode": "linked",
  "network": "mainnet",
  "humanAddress": "0x...",
  "agentAddress": "0x...",
  "agentPrivateKey": "0x...",
  "sessionId": "uuid",
  "handoffUrl": "https://selfagentid.xyz/cli/register?session=...",
  "status": "pending",
  "createdAt": "2026-02-22T..."
}
```

--------------------------------

### Query Documentation via HTTP GET

Source: https://docs.self.xyz/webhooks/signature-verification

To ask questions about the documentation, perform an HTTP GET request to the page URL with an 'ask' query parameter. The response will provide a direct answer and relevant excerpts.

```http
GET https://docs.self.xyz/webhooks/signature-verification.md?ask=<question>
```

--------------------------------

### Example Prompt: Authenticated Fetch

Source: https://docs.self.xyz/self-agent-id/agent-builder/mcp-user

Use this prompt to make a signed HTTP request to a protected endpoint.

```plaintext
Make an authenticated request to https://api.example.com/protected.
```

--------------------------------

### Example Prompt: Sign HTTP Request

Source: https://docs.self.xyz/self-agent-id/agent-builder/mcp-user

Use this prompt to generate authentication headers for an HTTP POST request.

```plaintext
Sign an HTTP POST request to https://api.example.com/data with body {"query": "test"}.
```

--------------------------------

### Install Self Agent ID CLI (Rust)

Source: https://docs.self.xyz/self-agent-id/cli

Install the Self Agent ID SDK using cargo and then invoke the CLI.

```bash
cargo install self-agent-sdk
# Then use:
self-agent register init ...
```

--------------------------------

### Query Documentation with 'ask' Parameter

Source: https://docs.self.xyz/self-connect/developer-guide

To get dynamic answers and clarifications not explicitly present on a page, use the `ask` query parameter with an HTTP GET request to the documentation URL. This allows for AI-driven querying of the documentation content.

```http
GET https://docs.self.xyz/self-connect/developer-guide.md?ask=<question>
```

--------------------------------

### Example Prompt: List Agents for Address

Source: https://docs.self.xyz/self-agent-id/agent-builder/mcp-user

Use this prompt to list all agents registered to a specific human address on the mainnet.

```plaintext
List all agents registered to 0xYourAddress on mainnet.
```

--------------------------------

### Example Prompt: Look up Agent

Source: https://docs.self.xyz/self-agent-id/agent-builder/mcp-user

Use this prompt to look up a Self Agent ID on the mainnet.

```plaintext
Look up Self Agent ID #5 on mainnet.
```

--------------------------------

### Registration Status Example Response

Source: https://docs.self.xyz/self-agent-id/rest-api

Example response from polling registration status, indicating the stage, agent ID, agent address, transaction hash, and session token.

```json
{
  "stage": "completed",
  "agentId": 42,
  "agentAddress": "0x83fa...ff00",
  "txHash": "0xabc...",
  "sessionToken": "enc_..."
}
```

--------------------------------

### Install Self Agent ID CLI (TypeScript)

Source: https://docs.self.xyz/self-agent-id/cli

Install the Self Agent ID CLI globally using npm or use npx for direct execution.

```bash
npm install -g @selfxyz/agent-sdk
# or use npx:
npx @selfxyz/agent-sdk register init ...
```

--------------------------------

### Agent-to-Chain (Direct) Smart Contract Example

Source: https://docs.self.xyz/self-agent-id/verification-patterns

Provides a Solidity smart contract example for the Agent-to-Chain (Direct) pattern, where an agent calls a contract directly using `msg.sender`. The contract inherits from `AgentGate` and uses `onlyVerifiedAgent` modifier.

```solidity
import { AgentGate } from "./AgentGate.sol";

contract MyProtocol is AgentGate {
    constructor(address registry) AgentGate(registry) {}

    function protectedAction() external onlyVerifiedAgent {
        // Only registered, human-backed agents can call this
    }
}
```

--------------------------------

### CI Integration Test Setup

Source: https://docs.self.xyz/verification-flows/test-vs-live

Configure environment variables for running integration tests in a CI environment using test keys and a test flow ID. This setup is crucial for simulating verification processes without incurring production costs.

```typescript
// In CI environment:
process.env.SELF_API_KEY = 'sk_test_...';
process.env.SELF_FLOW_ID = '<test flow uuid>';
process.env.SELF_WEBHOOK_SECRET = 'whsec_test_...';

// The test creates a session, simulates a mock-passport completion,
// and asserts the webhook handler fires with the expected payload.
```

--------------------------------

### Example Prompt: Register Agent

Source: https://docs.self.xyz/self-agent-id/agent-builder/mcp-user

Use this prompt to initiate the registration process for a Self Agent on the mainnet, requiring passport verification.

```plaintext
Register me as a Self Agent on mainnet. I'll scan my passport to prove I'm human.
```

--------------------------------

### Query Documentation Dynamically

Source: https://docs.self.xyz/reference

To get information not explicitly present on a page, perform an HTTP GET request to the current page URL with the 'ask' query parameter. The question should be specific and in natural language.

```HTTP
GET https://docs.self.xyz/reference.md?ask=<question>
```

--------------------------------

### Example Prompt: Verify Agent

Source: https://docs.self.xyz/self-agent-id/agent-builder/mcp-user

Use this prompt to verify if a given address is a registered agent on the mainnet.

```plaintext
Verify if address 0x83fa4380903fecb801F4e123835664973001ff00 is a registered agent on mainnet.
```

--------------------------------

### Request Documentation with a Question

Source: https://docs.self.xyz/backend-integration/basic-integration

Use this GET request to ask a specific question about the documentation. The response will include a direct answer and relevant excerpts.

```http
GET https://docs.self.xyz/self-pass-legacy/basic-integration.md?ask=<question>
```

--------------------------------

### Self Enterprise Client Initialization and Session Creation

Source: https://docs.self.xyz/migrate/from-self-pass-sdk

Example of initializing `SelfClient` with an API key and creating a new verification session with a specified flow ID.

```typescript
import { SelfClient } from '@selfxyz/enterprise-sdk';

const self = new SelfClient({ apiKey: process.env.SELF_API_KEY! });

// When the user wants to verify:
app.post('/start-verification', async (req, res) => {
  const session = await self.sessions.create({
    flowId: process.env.SELF_FLOW_ID!,
    externalUuid: req.user.id,
  });
  res.json({ verificationUrl: session.verificationUrl });
});
```

--------------------------------

### Query Documentation

Source: https://docs.self.xyz/dashboard/people

To get specific information not directly on the page, make an HTTP GET request to the current page URL with an 'ask' query parameter containing your question.

```HTTP
GET https://docs.self.xyz/dashboard/people.md?ask=<question>
```

--------------------------------

### Query Documentation Dynamically

Source: https://docs.self.xyz/reference/document-specifications

To get information not directly available on a page, send an HTTP GET request to the current page URL with the 'ask' query parameter. The question should be specific and in natural language.

```HTTP
GET https://docs.self.xyz/reference/document-specifications.md?ask=<question>
```

--------------------------------

### Query Documentation with 'ask' Parameter

Source: https://docs.self.xyz/dashboard

To get specific information not directly on a page, make an HTTP GET request to the page URL with the 'ask' query parameter. The question should be in natural language.

```HTTP
GET https://docs.self.xyz/dashboard.md?ask=<question>
```

--------------------------------

### Query Documentation with HTTP GET

Source: https://docs.self.xyz/webhooks/best-practices

Use this method to ask questions about the documentation when the answer is not explicitly present. The question should be specific and self-contained.

```http
GET https://docs.self.xyz/webhooks/best-practices.md?ask=<question>
```

--------------------------------

### Querying Documentation with 'ask' Parameter

Source: https://docs.self.xyz/dashboard/webhooks

To get specific information not directly on the page, make an HTTP GET request to the current page URL and include an 'ask' query parameter with your question. The response will provide a direct answer along with relevant excerpts and sources.

```http
GET https://docs.self.xyz/dashboard/webhooks.md?ask=<question>
```

--------------------------------

### Registration Modes Decision Guide

Source: https://docs.self.xyz/self-agent-id/registration-modes

A flowchart to help decide which registration mode to use based on key type and authentication method.

```text
                  ┌─────────────────────┐
                  │ What key type does   │
                  │ your agent use?      │
                  └────────┬────────────┘
                           │
              ┌────────────┴────────────┐
              │                         │
         Ed25519                     ECDSA
              │                         │
     ┌────────┴────────┐      ┌────────┴─────────────┐
     │ Need human      │      │ How should the       │
     │ wallet binding? │      │ human authenticate?  │
     └───┬─────────┬───┘      └──┬──────┬──────┬─────┘
         │         │             │      │      │
        No        Yes         Wallet  Social  Passkey
         │         │             │    login
         ▼         ▼             │      │      │
    ed25519   ed25519-      ┌───┴───┐  ▼      ▼
              linked        │       │ privy  smartwallet
                           Yes     No
                            │      │
                            ▼      ▼
                         linked  wallet-free
```

--------------------------------

### Step 1: Create Registration Session

Source: https://docs.self.xyz/self-agent-id/cli

Initiates a new agent registration session. Use `--network testnet` for development environments.

```bash
self-agent register init \
  --mode linked \
  --human-address 0xYourWalletAddress \
  --network mainnet \
  --out .self/session.json
```

--------------------------------

### API Key Format

Source: https://docs.self.xyz/dashboard/api-keys

API keys have a prefix that indicates the environment. Test keys start with 'sk_test_' and live keys with 'sk_live_'.

```text
sk_test_…
sk_live_…
```

--------------------------------

### Get Visa Status API Response Example

Source: https://docs.self.xyz/self-agent-id/celo-agent-visa

This JSON object represents the response from the GET /api/visa/{chainId}/{agentId} endpoint, detailing an agent's visa tier, metrics, and eligibility.

```json
{
  "agentId": 42,
  "chainId": 42220,
  "tier": 1,
  "tierName": "Tourist Visa",
  "metrics": {
    "transactionCount": 1250,
    "volumeUsd": 6200,
    "lastUpdated": 1745123456
  },
  "eligibility": {
    "1": true,
    "2": true,
    "3": false
  },
  "reviewRequestedTier": 0,
  "manualReviewApproved": false
}
```

--------------------------------

### Set Up Issuer Account with Viem

Source: https://docs.self.xyz/self-connect/developer-guide

Initialize an issuer account using a private key and create a Viem wallet client for the Alfajores testnet. Ensure the private key is kept secure.

```typescript
import { createWalletClient, http, parseEther } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { celoAlfajores } from "viem/chains";

// Issuer private key - KEEP SECURE
const ISSUER_PRIVATE_KEY = process.env.ISSUER_PRIVATE_KEY;
const account = privateKeyToAccount(ISSUER_PRIVATE_KEY);

// Create Viem client
const walletClient = createWalletClient({
  account,
  transport: http(),
  chain: celoAlfajores
});

const issuerAddress = account.address;
console.log("Issuer Address:", issuerAddress);
```

--------------------------------

### Initialize SelfClient

Source: https://docs.self.xyz/sdk/nodejs

Instantiate the SelfClient by providing your API key. The client automatically determines whether to communicate with test or live environments based on the API key prefix.

```APIDOC
## Initialize SelfClient

Instantiate the SelfClient by providing your API key. The client automatically determines whether to communicate with test or live environments based on the API key prefix.

```ts
import { SelfClient } from '@selfxyz/enterprise-sdk';

const self = new SelfClient({
  apiKey: process.env.SELF_API_KEY!, // sk_test_... or sk_live_...
});
```

**Parameters**

- **apiKey** (string) - Required - Your Self Enterprise API key (e.g., `sk_test_...` or `sk_live_...`).
```

--------------------------------

### A2A Protocol (JSON-RPC) Request Example

Source: https://docs.self.xyz/self-agent-id/rest-api

Example request for the Agent-to-Agent JSON-RPC 2.0 endpoint, demonstrating a 'message/send' intent.

```JSON
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "message/send",
  "params": {
    "message": {
      "role": "user",
      "parts": [{ "type": "data", "data": { "intent": "register" } }]
    }
  }
}
```

--------------------------------

### Metadata and Agent URI Operations

Source: https://docs.self.xyz/self-agent-id/smart-contracts

Illustrates setting and getting the agent's URI and metadata key-value pairs, as well as setting the agent wallet with a signature.

```solidity
// Set/get agent URI (ERC-8004)
registry.setAgentURI(agentId, "https://example.com/agent.json");

// Set/get metadata key-value pairs
registry.setMetadata(agentId, "name", abi.encode("My Agent"));
bytes memory value = registry.getMetadata(agentId, "name");

// Set agent wallet (requires EIP-712 signature from newWallet)
registry.setAgentWallet(agentId, newWallet, deadline, signature);
```

--------------------------------

### Initialize SelfClient

Source: https://docs.self.xyz/sdk/api-reference

Instantiate the SelfClient with your API key. The environment (test or live) is determined by the key's prefix. An error is thrown if the API key is not provided.

```typescript
new SelfClient({ apiKey: string })
```

--------------------------------

### Query Documentation with 'ask' Parameter

Source: https://docs.self.xyz/sdk/api-reference

Perform an HTTP GET request to query the documentation dynamically. Use this when the answer is not explicitly present, you need clarification, or want to retrieve related documentation sections.

```http
GET https://docs.self.xyz/sdk/api-reference.md?ask=<question>
```

--------------------------------

### Query Documentation API

Source: https://docs.self.xyz/webhooks/overview

Demonstrates how to ask questions about the documentation using the API. This is useful for retrieving specific information or clarification.

```http
GET https://docs.self.xyz/webhooks/overview.md?ask=<question>
```

--------------------------------

### GET /api/health

Source: https://docs.self.xyz/self-agent-id/rest-api

Returns the service health status. No authentication required.

```APIDOC
## GET /api/health

### Description
Returns service health status. No authentication required.

### Method
GET

### Endpoint
/api/health
```

--------------------------------

### GET /api/verify-status/{chainId}/{agentId}

Source: https://docs.self.xyz/self-agent-id/rest-api

Returns the real-time proof status and freshness for an agent.

```APIDOC
## GET /api/verify-status/{chainId}/{agentId}

### Description
Returns real-time proof status and freshness.

### Method
GET

### Endpoint
/api/verify-status/{chainId}/{agentId}

### Parameters
#### Path Parameters
- **chainId** (integer) - Required - The ID of the blockchain network.
- **agentId** (integer) - Required - The unique identifier of the agent.

### Response
#### Success Response (200)
- **verified** (boolean) - Indicates if the agent is verified.
- **proofType** (string) - The type of proof.
- **registeredAtBlock** (string) - The block number at which the agent was registered.
- **providerAddress** (string) - The address of the proof provider.
```

--------------------------------

### Step 2: Open Browser Handoff

Source: https://docs.self.xyz/self-agent-id/cli

Opens the generated handoff URL in the default browser, prompting the user to complete the verification process via the Self app.

```bash
self-agent register open --session .self/session.json
```

--------------------------------

### Get Verification Status Endpoint

Source: https://docs.self.xyz/self-agent-id/rest-api

Retrieve real-time proof status and freshness for an agent.

```HTTP
GET /api/verify-status/{chainId}/{agentId}
```

--------------------------------

### Query Documentation Dynamically

Source: https://docs.self.xyz/migrate

Perform an HTTP GET request on the current page URL with the `ask` query parameter to dynamically query the documentation. The question should be specific and in natural language. Use this when the answer is not explicitly present, you need clarification, or want to retrieve related sections.

```http
GET https://docs.self.xyz/migrate.md?ask=<question>
```

--------------------------------

### Example Formatted Identifiers

Source: https://docs.self.xyz/self-connect/architecture-and-how-it-works

Illustrates the format of identifiers after prefix and plaintext are combined, as used in ODIS.

```plaintext
Phone: "PHONE_NUMBER://+12345678901"
Twitter: "twitter://@alice"
```

--------------------------------

### Step 5: Export Agent Credentials

Source: https://docs.self.xyz/self-agent-id/cli

Outputs the agent's address, public key, agent ID, and private key for use in your agent's environment.

```bash
self-agent register export --session .self/session.json
```

--------------------------------

### Get QR Code

Source: https://docs.self.xyz/self-agent-id/rest-api

Returns the QR code payload and deep link for the current session.

```APIDOC
## GET /api/agent/register/qr?token={sessionToken}

### Description
Returns the QR code payload and deep link for the current session.

### Method
GET

### Endpoint
/api/agent/register/qr

### Parameters
#### Query Parameters
- **token** (string) - Required - The session token for the registration process.
```

--------------------------------

### Query Documentation Dynamically

Source: https://docs.self.xyz/billing

Perform an HTTP GET request to query the documentation dynamically. Use this when the answer is not explicitly present, you need clarification, or want to retrieve related sections.

```http
GET https://docs.self.xyz/billing.md?ask=<question>
```

--------------------------------

### GET /api/cards/{chainId}/{agentId}

Source: https://docs.self.xyz/self-agent-id/rest-api

Retrieves the A2A-compatible agent identity card in JSON format.

```APIDOC
## GET /api/cards/{chainId}/{agentId}

### Description
Returns the A2A-compatible agent identity card in JSON format.

### Method
GET

### Endpoint
/api/cards/{chainId}/{agentId}

### Parameters
#### Path Parameters
- **chainId** (integer) - Required - The ID of the blockchain network.
- **agentId** (integer) - Required - The unique identifier of the agent.
```

--------------------------------

### Query Documentation via HTTP GET

Source: https://docs.self.xyz/self-agent-id/cli

Use this method to ask questions about the documentation when the answer is not explicitly present on the page. The question should be specific and in natural language.

```http
GET https://docs.self.xyz/self-agent-id/cli.md?ask=<question>
```

--------------------------------

### Get Agent Card Endpoint

Source: https://docs.self.xyz/self-agent-id/rest-api

Retrieve the A2A-compatible agent identity card in JSON format.

```HTTP
GET /api/cards/{chainId}/{agentId}
```

--------------------------------

### Query Documentation via HTTP GET

Source: https://docs.self.xyz/self-agent-id/agent-builder/mcp-user

Use this method to dynamically query the documentation for specific information not explicitly present on the page. Include your question as the 'ask' query parameter.

```HTTP
GET https://docs.self.xyz/self-agent-id/agent-builder/mcp-user.md?ask=<question>
```

--------------------------------

### Standalone Ed25519 Registration Init

Source: https://docs.self.xyz/self-agent-id/cli

Initiates a registration session for an agent identified solely by its Ed25519 public key. Requires a signature over the session challenge.

```bash
self-agent register init \
  --mode ed25519 \
  --ed25519-pubkey <hex> \
  --ed25519-signature <hex> \
  --network mainnet \
  --out .self/session.json
```

--------------------------------

### GET /api/reputation/{chainId}/{agentId}

Source: https://docs.self.xyz/self-agent-id/rest-api

Retrieves the agent's verification strength score from the proof provider.

```APIDOC
## GET /api/reputation/{chainId}/{agentId}

### Description
Returns the agent's verification strength score from the proof provider.

### Method
GET

### Endpoint
/api/reputation/{chainId}/{agentId}

### Parameters
#### Path Parameters
- **chainId** (integer) - Required - The ID of the blockchain network.
- **agentId** (integer) - Required - The unique identifier of the agent.

### Response
#### Success Response (200)
- **score** (integer) - The verification strength score.
- **hasProof** (boolean) - Indicates if a proof exists.
- **providerName** (string) - The name of the proof provider.
- **proofType** (string) - The type of proof.
```

--------------------------------

### Get Reputation Score Endpoint

Source: https://docs.self.xyz/self-agent-id/rest-api

Obtain an agent's verification strength score from the proof provider.

```HTTP
GET /api/reputation/{chainId}/{agentId}
```

--------------------------------

### Register Agent via CLI

Source: https://docs.self.xyz/self-agent-id/agent-builder

Initialize, open, wait for, and export an agent's private key using the Self Agent ID CLI. Ensure the CLI is installed globally.

```bash
# Install the CLI (comes with the SDK)
npm install -g @selfxyz/agent-sdk

# Initialize registration
self-agent register init \
  --mode linked \
  --human-address 0xYourWallet \
  --network mainnet \
  --minimum-age 18 \
  --ofac

# Open the browser handoff URL
self-agent register open --session .self/session-*.json

# Wait for verification to complete
self-agent register wait --session .self/session-*.json

# Export the agent private key
self-agent register export --session .self/session-*.json --unsafe --print-private-key
```

--------------------------------

### Access Control with AgentGate

Source: https://docs.self.xyz/self-agent-id/smart-contracts

Example of using AgentGate as a base contract to restrict access to functions for verified agents only.

```solidity
import { AgentGate } from "./AgentGate.sol";

contract MyProtocol is AgentGate {
    constructor(address _registry) AgentGate(_registry) {}

    function protectedAction() external onlyVerifiedAgent {
        // Only verified agents can call this
        bytes32 agentKey = bytes32(uint256(uint160(msg.sender)));
        uint256 agentId = registry.getAgentId(agentKey);
        // ... your logic
    }
}
```

--------------------------------

### Optimizing Read Operations with Viem Public Actions

Source: https://docs.self.xyz/self-connect/developer-guide

Shows how to use Viem's public client directly for read-only operations, eliminating the need for a wallet client and improving efficiency.

```typescript
import { createPublicClient, http } from "viem";
import { celo } from "viem/chains";

const publicClient = createPublicClient({
  chain: celo,
  transport: http()
});

// No wallet needed for reads
const attestations = await publicClient.readContract({
  address: FEDERATED_ATTESTATIONS_ADDRESS,
  abi: federatedAttestationsABI,
  functionName: "lookupAttestations",
  args: [obfuscatedIdentifier, trustedIssuers]
});
```

--------------------------------

### Open-source Self Pass Verifier Configuration

Source: https://docs.self.xyz/migrate/from-self-pass-sdk

Example of configuring the `SelfBackendVerifier` with inline predicate configurations using `InMemoryConfigStorage`.

```typescript
const verifier = new SelfBackendVerifier({
  scope: 'my-app',
  endpoint: 'https://myapp.com/verify',
  configStore: new InMemoryConfigStorage({
    minimumAge: 18,
    excludedCountries: ['USA'],
    ofac: true,
  }),
});
```

--------------------------------

### Create a Verification Session

Source: https://docs.self.xyz/get-started/concepts

Use the SDK to create a new verification session, passing the flow ID. The session will have a credit cost determined at creation.

```javascript
sessions.create({
  flowId: "flow_12345"
});
```

--------------------------------

### Get QR Code for Registration

Source: https://docs.self.xyz/self-agent-id/rest-api

Retrieves the QR code payload and deep link for an ongoing registration session.

```http
GET /api/agent/register/qr?token={sessionToken}
```
Tokens:
Raw