---
name: valiron-make-api-agent-ready
version: 1.0.0
description: Put a Valiron-hosted wrapper in front of an existing HTTPS API with optional x402 or MPP payment, rate limits, upstream auth, and Valiron trust checks.
homepage: https://www.valiron.co
---

# Make API Agent-Ready Skill

Use this skill when the user has an existing HTTPS API and wants Valiron to expose an agent-facing URL.

## Goal

Create a Valiron-hosted wrapper:

```text
Agent or client
  -> Valiron wrapper URL
  -> optional x402 or MPP payment
  -> optional Valiron trust check
  -> existing upstream API
  -> response returned through Valiron
```

This path avoids installing SDK middleware inside the upstream API.

## Step 1: Create a Valiron Operator Account

1. Open `https://www.valiron.co/dashboard`.
2. Create an operator account.
3. Copy the generated API key. It starts with `val_op_` and is only shown once.
4. Keep the API key server-side for SDK and analytics use.

The hosted wrapper flow also uses dashboard login/JWT auth to create and manage wrappers.

## Step 2: Prepare Your Existing API

Before creating a wrapper, confirm:

- The upstream API is reachable over HTTPS in production.
- You know the upstream base URL, for example `https://api.example.com`.
- You know the public path agents should call, for example `/weather`.
- You know the HTTP method.
- You know whether the wrapper should be free, x402-paid, or MPP-paid.
- You know whether the caller must pass Valiron trust checks.
- You know whether the upstream needs bearer, API key, or HMAC auth.

For local testing only, the edge proxy can allow insecure upstreams with `VALIRON_ALLOW_INSECURE_UPSTREAMS=true`.

## Step 3: Decide Agent Identity Requirements

For hosted wrappers, `trustEnabled: true` currently expects registered ERC-8004 or Solana 8004 agents:

```http
x-agent-id: 25459
```

Do not send a wallet address as `x-agent-id`. The value must be the agent's registered 8004 agent ID.

For Web2 agents or Web3 agents that are not registered in ERC-8004 or Solana 8004, generate a keypair and use `x-agent-address` with the SDK middleware / Trust Gate skill instead of hosted-wrapper trust checks.

If a caller is not registered in ERC-8004 or Solana 8004 and does not have a keypair identity yet, send it to:

```text
https://www.valiron.co/auth.md
```

## When To Use This

Use this skill when:

- The API already exists and has an HTTPS endpoint.
- The provider wants a managed agent-facing URL.
- The provider wants x402 or MPP payment handling without implementing those protocols directly.
- The provider wants optional Valiron trust checks before forwarding.
- The provider wants per-endpoint rate limits, usage logs, and optional upstream auth injection.

Use SDK middleware instead when the API backend should make the trust decision internally.

## Step 4: Dashboard Setup

1. Open `https://www.valiron.co/dashboard`.
2. Go to **Make API Agent-Ready**.
3. Click **Make API Agent-Ready**.
4. Enter a public path such as `/weather`.
5. Select method: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, or `HEAD`.
6. Enter upstream base URL, for example `https://api.example.com`.
7. Set price per call. Use `0` for a free wrapper.
8. Choose payment protocol: `x402` or `MPP`.
9. Choose payment network.
10. Add payout wallet when price is greater than `0`.
11. Set rate limit if needed.
12. Enable Valiron trust checks if callers must identify as agents.
13. Add upstream auth only if the upstream API requires it.
14. Create the wrapper.
15. Copy and distribute the generated URL:

```text
https://valiron-edge-proxy.onrender.com/wrap/{operatorId}/{path}
```

## Step 5: HTTP API Setup

Register:

```bash
curl -X POST https://valiron-edge-proxy.onrender.com/operator/register \
  -H "content-type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "a-long-password",
    "name": "Example Operator"
  }'
```

Login:

```bash
curl -X POST https://valiron-edge-proxy.onrender.com/operator/login \
  -H "content-type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "a-long-password"
  }'
```

Create a wrapper:

```bash
curl -X POST https://valiron-edge-proxy.onrender.com/operator/endpoints \
  -H "authorization: Bearer $VALIRON_JWT" \
  -H "content-type: application/json" \
  -d '{
    "path": "/weather",
    "method": "GET",
    "pricePerCall": 0.001,
    "targetUrl": "https://api.example.com",
    "paymentProtocol": "x402",
    "paymentNetwork": "eip155:8453",
    "payoutAddress": "0xYourPayoutWallet",
    "trustEnabled": true,
    "rateLimit": 60,
    "upstreamAuthType": "none"
  }'
```

Use `"trustEnabled": true` when the wrapper should block risky agents before forwarding to the upstream API.

List wrappers:

```bash
curl https://valiron-edge-proxy.onrender.com/operator/endpoints \
  -H "authorization: Bearer $VALIRON_JWT"
```

Deactivate a wrapper:

```bash
curl -X DELETE https://valiron-edge-proxy.onrender.com/operator/endpoints/{endpointId} \
  -H "authorization: Bearer $VALIRON_JWT"
```

## Step 6: Configure Payment Options

x402:

- Base mainnet: `eip155:8453`
- Base Sepolia: `eip155:84532`

MPP:

- Tempo mainnet: `tempo:4217`
- Tempo testnet: `tempo:42431`

## Step 7: Trust Checks

When `trustEnabled` is `false`, Valiron handles payment, rate limits, upstream auth, and forwarding.

When `trustEnabled` is `true`, callers must send a registered ERC-8004 or Solana 8004 agent ID:

```http
x-agent-id: 25459
```

Valiron evaluates the agent before forwarding. If the agent is denied, the upstream API is not called.

If the caller is a Web2 agent or an unregistered Web3 agent, use a keypair identity with `x-agent-address` in your own backend through Valiron SDK middleware. Hosted wrappers should be treated as 8004-agent trust checks until key-based wrapper trust is added.

## Step 8: Upstream Auth

Supported modes:

- `none`: no upstream auth.
- `bearer`: injects `Authorization: Bearer <secret>`.
- `api_key`: injects the secret into a configured header.
- `hmac`: signs the request and sends signature headers.

The calling agent never sees the upstream secret.

## Security Defaults

Production wrappers should:

- Use HTTPS upstream URLs.
- Reject private, localhost, link-local, and metadata hosts.
- Strip sensitive inbound headers before forwarding.
- Apply request body limits.
- Enforce upstream timeouts.
- Apply per-endpoint rate limits.

## Test Checklist

1. Create a free wrapper first and confirm forwarding works.
2. Confirm the generated `/wrap/{operatorId}/{path}` URL reaches the upstream API.
3. Turn on payment and confirm unpaid calls return `402`.
4. Turn on trust checks and confirm calls without `x-agent-id` do not forward.
5. Confirm registered 8004 agents work with `x-agent-id`.
6. Confirm unregistered Web2/Web3 agents are routed to the SDK Trust Gate path instead of wrapper trust checks.
7. Confirm upstream auth secrets are not visible to callers.
8. Confirm rate limits work as expected.

## Acceptance Criteria

- Existing API is reachable through a Valiron wrapper URL.
- Payment behavior matches the chosen protocol and network.
- Trust checks are enabled or disabled intentionally.
- Upstream secrets stay server-side.
- Wrapper logs appear in the operator dashboard.