> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yativo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agentic Wallets

> Programmable wallets for AI agents — send crypto, pay for x402 APIs, and track spending with full audit trails

Agentic Wallets give AI agents their own self-custodial crypto wallets. Each wallet is a programmable spending account that AI services can use to send payments, pay for x402 paywalled APIs, and keep an immutable audit trail of every dollar spent.

Built for the agentic economy — where AI agents need to pay for services, tools, and data autonomously.

***

## How It Works

<Steps>
  <Step title="Create a wallet">
    Create an agentic wallet from the dashboard or via API. Each wallet gets its own on-chain address with USDC funding support.
  </Step>

  <Step title="Activate with 2FA">
    Activate the wallet using email OTP and/or TOTP verification. This ensures only the wallet owner can authorize the wallet for agent use.
  </Step>

  <Step title="Add connectors">
    Generate API keys (connectors) that your AI agent uses to authenticate. Each connector can have its own spending limits and permissions.
  </Step>

  <Step title="Fund the wallet">
    Deposit USDC into the wallet's on-chain address, or use the manual funding endpoint to top up from your main account.
  </Step>

  <Step title="Let your agent transact">
    The agent uses its connector API key to send payments, pay for x402 APIs, and check balances — all with per-transaction audit trails.
  </Step>
</Steps>

***

## Key Features

<CardGroup cols={2}>
  <Card title="Per-Agent API Keys" icon="key">
    Each connector gets a unique API key (`yac_...`) with configurable spending limits. Revoke a connector without affecting the wallet.
  </Card>

  <Card title="x402 Protocol Support" icon="money-bill-wave">
    Built-in support for the x402 payment protocol. Your agent can fetch paywalled APIs and the wallet auto-pays the 402 response.
  </Card>

  <Card title="Spending Limits" icon="shield">
    Set per-transaction, daily, and monthly limits at the wallet level and per connector. Enforce budget controls before the agent can overspend.
  </Card>

  <Card title="Full Audit Trail" icon="receipt">
    Every transaction records the service name, URL, payment reason, and category. Built for compliance and cost attribution.
  </Card>

  <Card title="Auto-Funding" icon="arrows-rotate">
    Configure automatic top-ups when the wallet balance drops below a threshold. Funds are pulled from your main account.
  </Card>

  <Card title="Multi-Chain Support" icon="link">
    Wallets support USDC across multiple chains. Pay services on any supported network.
  </Card>
</CardGroup>

***

## Wallet Lifecycle

```mermaid theme={null}
stateDiagram-v2
    [*] --> Created: POST /agentic-wallets/create
    Created --> Activating: Send OTP
    Activating --> Active: Verify OTP + Activate
    Active --> Active: Transact, fund, add connectors
    Active --> Deactivated: POST /deactivate
    Deactivated --> [*]
```

| Status | Description |
| - | - |
| `created` | Wallet exists but cannot transact until activated |
| `activating` | OTP verification in progress |
| `active` | Fully operational — agents can transact |
| `suspended` | Temporarily halted by admin (e.g., suspicious activity) |
| `deactivated` | Permanently disabled by the owner |

***

## Connectors

Connectors are API keys tied to a specific wallet. Think of them as "agent credentials" — each AI agent or service integration gets its own connector, with its own limits and capabilities.

| Field | Description |
| - | - |
| `connector_type` | `anthropic`, `openai`, `polymarket`, `kalshi`, `openclaw` or `custom` |
| `name` | Human-readable label (e.g., "Production Agent") |
| `api_key` | Starts with `yac_`. Returned once, when the connector is created |
| `max_per_transaction` | Max USD amount per transaction |
| `max_daily_amount` | Max USD amount per day |
| `max_monthly_amount` | Max USD amount per month |
| `allowed_capabilities` | What the agent may do: `transfer`, `x402`, `prediction_market`. Defaults to `transfer` only |
| `allowed_assets`, `allowed_chains` | Optional allow-lists |
| `allowed_ips`, `allowed_domains` | Optional request origin allow-lists |
| `prediction_market_config` | Extra limits for prediction market trades. See [Prediction markets](#prediction-markets) |

Limits must be consistent: `max_per_transaction` can't exceed `max_daily_amount`, which can't exceed `max_monthly_amount`. Any limit you leave out falls back to the wallet's global limit.

You can have multiple connectors per wallet for different agents or environments.

### Capabilities

Every connector has an explicit list of capabilities. A request outside that list is rejected.

| Capability | Allows |
| - | - |
| `transfer` | `POST /agent/transact` payments |
| `x402` | `POST /agent/x402-fetch` paid requests |
| `prediction_market` | Searching and trading prediction markets |

New connectors get `transfer` only. Add `x402` or `prediction_market` deliberately when you create or update the connector.

***

## Agent API

Once a connector is active, the agent authenticates with its API key (`Authorization: Bearer yac_...`) and calls the Agent API directly:

| Endpoint | Capability | Description |
| - | - | - |
| `GET /agent/openapi.json` | — | Machine-readable description of the Agent API. No auth |
| `GET /agent/capabilities` | — | What this connector can do, its limits and remaining budget |
| `POST /agent/transact` | `transfer` | Send a crypto payment |
| `GET /agent/balance` | — | Check wallet balance |
| `GET /agent/transactions` | — | List recent transactions |
| `POST /agent/x402-fetch` | `x402` | Fetch a URL with automatic x402 payment |
| `GET /agent/markets/search` | `prediction_market` | Search prediction markets |
| `POST /agent/markets/trade` | `prediction_market` | Buy or sell a market position |
| `GET /agent/positions` | `prediction_market` | List open positions |

The Agent API allows 30 requests per minute.

### Discover capabilities

Agents can check what they're allowed to do before acting:

```bash theme={null}
curl 'https://crypto-api.yativo.com/api/v1/agent/capabilities?wallet_id=aw_01abc123' \
  -H 'Authorization: Bearer yac_...'
```

```json theme={null}
{
  "success": true,
  "data": {
    "wallet_id": "aw_01abc123",
    "wallet_address": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
    "chain": "solana",
    "balance": 248.5,
    "capabilities": ["transfer", "prediction_market"],
    "limits": {
      "max_per_transaction": 50,
      "max_daily_amount": 500,
      "max_monthly_amount": 5000,
      "remaining_daily": 420,
      "remaining_monthly": 4780,
      "allowed_assets": [],
      "allowed_chains": []
    },
    "prediction_market": {
      "max_position_usd": 25,
      "allowed_categories": [],
      "allowed_providers": []
    },
    "supported_assets": ["..."]
  }
}
```

`GET /agent/openapi.json` returns an OpenAPI description of the same surface, so any OpenAPI-aware agent framework (LangChain, GPT Actions, custom code) can discover it.

### Send a Payment

```bash theme={null}
curl -X POST 'https://crypto-api.yativo.com/api/v1/agent/transact' \
  -H 'Authorization: Bearer yac_connector_api_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "wallet_id": "aw_01abc123",
    "amount": 5.00,
    "asset": "USDC",
    "recipient_address": "0x9F8b3A2c1E4D7F6B5A4C3D2E1F0A9B8C7D6E5F4",
    "service_name": "OpenAI API",
    "service_url": "https://api.openai.com",
    "payment_reason": "GPT-4 inference for customer support bot",
    "payment_category": "ai_service"
  }'
```

```json Response theme={null}
{
  "success": true,
  "data": {
    "transaction_id": "atx_01pqr456",
    "tx_hash": "0xabc123...",
    "amount": 5.00,
    "asset": "USDC",
    "recipient_address": "0x9F8b...",
    "chain": "base",
    "status": "completed",
    "fee": 0.00,
    "is_free_transaction": true
  }
}
```

### x402 Protocol Fetch

The x402 protocol enables HTTP-native micropayments. When your agent fetches a URL that returns HTTP 402 (Payment Required), the wallet automatically pays and retries:

```bash theme={null}
curl -X POST 'https://crypto-api.yativo.com/api/v1/agent/x402-fetch' \
  -H 'Authorization: Bearer yac_connector_api_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "wallet_id": "aw_01abc123",
    "url": "https://api.example.com/premium-data",
    "method": "GET"
  }'
```

```json Response theme={null}
{
  "success": true,
  "data": {
    "status": 200,
    "paid": true,
    "payment": {
      "amount_usd": 0.01,
      "asset": "USDC",
      "network": "base",
      "pay_to": "0x..."
    },
    "body": { "premium_data": "..." }
  }
}
```

***

### Prediction markets

Connectors with the `prediction_market` capability can trade prediction markets from a **Solana** agentic wallet, paying in USDC. Every trade goes through the same limits and rules as a payment, and a trade that would move more USDC than authorized is refused.

**Search markets**

```bash theme={null}
curl 'https://crypto-api.yativo.com/api/v1/agent/markets/search?wallet_id=aw_01abc123&query=election&limit=10' \
  -H 'Authorization: Bearer yac_...'
```

| Query param | Description |
| - | - |
| `wallet_id` | Required. The agentic wallet |
| `query` | Search text |
| `category` | Filter by category |
| `limit` | Max results (default 20) |
| `provider` | Optional. Leave out to use the default |

**Place a trade**

```bash theme={null}
curl -X POST 'https://crypto-api.yativo.com/api/v1/agent/markets/trade' \
  -H 'Authorization: Bearer yac_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: trade-7f3a' \
  -d '{
    "wallet_id": "aw_01abc123",
    "market_id": "MARKET_ID_FROM_SEARCH",
    "outcome": "yes",
    "side": "buy",
    "amount": 10,
    "category": "politics",
    "reason": "Agent strategy signal"
  }'
```

| Field | Required | Description |
| - | - | - |
| `wallet_id` | Yes | The agentic wallet |
| `market_id` | Yes | From market search |
| `outcome` | Yes | `yes` or `no` |
| `side` | No | `buy` (default) or `sell` |
| `amount` | Yes | USD notional, paid in USDC |
| `category` | Only if the connector limits categories | The market's category |
| `reason`, `metadata` | No | Stored with the transaction for your records |

Send an `Idempotency-Key` header (or `idempotency_key` field) so a retried trade isn't placed twice.

**Trade limits** (set per connector in `prediction_market_config`):

* `max_position_usd` — largest single trade.
* `allowed_categories` — if set, trades must name one of these categories.
* `allowed_providers` — if set, only these providers can be used.

**List positions**

```bash theme={null}
curl 'https://crypto-api.yativo.com/api/v1/agent/positions?wallet_id=aw_01abc123' \
  -H 'Authorization: Bearer yac_...'
```

***

## Payment Categories

Every agent transaction requires a `payment_category` for audit and analytics:

| Category | Use Case |
| - | - |
| `ai_service` | Paying for AI model inference, embeddings, etc. |
| `prediction_market` | Placing bets or funding prediction contracts |
| `legal_escrow` | Escrow payments for legal or contractual obligations |
| `subscription` | Recurring service subscriptions |
| `purchase` | One-time purchases or API credits |
| `transfer` | Wallet-to-wallet transfers |
| `settlement` | Settling invoices or outstanding balances |
| `other` | Anything not covered above |

***

## Pricing

Agentic wallet pricing is tier-based. Check the current pricing:

```bash theme={null}
curl -X GET 'https://crypto-api.yativo.com/api/v1/agentic-wallets/pricing' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

Each plan includes a number of free transactions per month. Transactions beyond the free tier incur a small per-transaction fee.

***

## Next Steps

<CardGroup cols={2}>
  <Card title="API Reference" icon="code" href="/api-reference/agentic-wallets/create">
    Full endpoint reference for all agentic wallet operations.
  </Card>

  <Card title="Sandbox" icon="flask" href="/sandbox/agentic-wallets">
    Test agentic wallets in the sandbox environment.
  </Card>

  <Card title="Webhooks" icon="bell" href="/yativo-crypto/webhooks">
    Get notified on agent transaction events.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.