# Getting Started

toani Facilitate serves two roles. Choose your path:

| Role      | You Are                                                            | You Need                                                                                                    |
| --------- | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
| **Payer** | Operator who wants AI Agents to spend compliantly and autonomously | Complete identity verification, configure spending limits, obtain API Key, integrate MCP Gateway with Agent |
| **Payee** | Merchant or API provider accepting Agent payments                  | Register payment wallet, complete KYC, obtain API Key                                                       |

***

## Payer Onboarding

### Step 1: Connect Wallet

Visit toani Facilitate Dashboard and connect an Ethereum wallet (MetaMask, WalletConnect, or other RainbowKit-supported wallet). Your wallet address becomes your Facilitate ID.

### Step 2: Sign In (SIWE)

After connecting, the system prompts you to sign a message (Sign-In with Ethereum). This creates your account and issues a session.

### Step 3: Complete KYC

Go to Dashboard > KYC. The [zkMe](https://docs.zk.me/) Widget guides you through document upload and liveness detection. After verification, your compliance status is stored as a zero-knowledge proof, protecting your personal privacy.

### Step 4: Generate Payer API Key

Go to Dashboard > Payer and click "Generate API Key". Copy and securely save it; the key displays only once. The MCP Gateway uses this key to verify your identity during transactions.

### Step 5: Create Intent Mandate

Go to Dashboard > Payer > Intent Mandates and click "New Mandate":

| Field                 | Description                                    | Example                 |
| --------------------- | ---------------------------------------------- | ----------------------- |
| Title                 | Descriptive name                               | "Daily research budget" |
| Per-Transaction Limit | Maximum USDC per transaction                   | 5.00                    |
| Total Budget          | Maximum total USDC for this Mandate's lifetime | 50.00                   |
| Valid Days            | Days until expiration                          | 30                      |

Click "Create"; the system prompts you to sign (EIP-712 structured data signature). After signing, a W3C verifiable credential is generated, cryptographically binding your spending limits to your identity.

Your account can have only one active Mandate at a time. Signing a new Mandate automatically revokes the previous one.

### Step 6: Integrate MCP Gateway with Agent

Your Agent needs to connect to paid services through the MCP Gateway, which is the trust middleware handling payment interception, compliance checks, and AP2 verification.

**Environment Variables**:

```bash
# Required: gateway wallet EVM private key (must start with 0x)
EVM_PRIVATE_KEY=0x...

# Required: one or more downstream MCP service URLs (comma-separated)
DOWNSTREAM_MCP_URLS=https://mcp-service-1.example.com,https://mcp-service-2.example.com

# Optional: transport mode (auto | sse | streamable-http, default auto)
DOWNSTREAM_MCP_TRANSPORT=auto

# Optional: connection retry count (1-10, default 3)
DOWNSTREAM_CONNECT_RETRIES=3

# Required for compliance: Dashboard base URL and API Key
COMPLIANCE_BASE_URL=https://your-dashboard.example.com
COMPLIANCE_API_KEY=toani_xxxxxxxxxxxx

# Optional: compliance chain (default base)
COMPLIANCE_CHAIN=base
```

**Cursor IDE Configuration Example** (add to `.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "toani-facilitator": {
      "command": "npx",
      "args": ["-y", "@toani/facilitator"],
      "env": {
        "EVM_PRIVATE_KEY": "0x...",
        "DOWNSTREAM_MCP_URLS": "https://your-downstream-service.example.com",
        "COMPLIANCE_BASE_URL": "https://your-dashboard.example.com",
        "COMPLIANCE_API_KEY": "toani_xxxxxxxxxxxx"
      }
    }
  }
}
```

**Agent Payment Flow**:

1. Agent calls `call_service_tool`, passing tool name and arguments
2. Gateway queries downstream for payment requirements
3. Executes compliance pre-check (KYC + KYT) and AP2 assurance (merchant signature + VC verification + budget check)
4. Within limit: gateway wallet pays automatically
5. Exceeds limit: returns `WALLET_APPROVAL_REQUIRED` challenge; browser wallet must manually sign
6. After successful payment, transaction record is written to Dashboard asynchronously

***

## Payee Onboarding

### Steps 1-2: Connect Wallet and Sign In

Same as payer onboarding.

### Step 3: Complete KYC

Same as payer onboarding: go to Dashboard > KYC and complete zkMe verification.

### Step 4: Bind Payment Wallet

Go to Dashboard > Payee and enter your USDC payment address. This address receives all x402 settlement funds. Binding is permanent and cannot be changed by you.

### Step 5: Generate Payee API Key

On the Payee page, click "Generate API Key". This key is used for payee compliance verification.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.toani.ai/toani-facilitate/getting-started.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.