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

# Agent execution (x402)

> Buy an unsigned, ready-to-sign vault transaction with a $0.05 micropayment — no account, no API key, non-custodial.

Any agent can go from *"where should this USDC earn?"* to *capital deployed* in three paid calls against `https://mcp.barker.money` — with no Barker account, no API key, and no custody handover. You pay per call via [x402](https://www.x402.org/) (HTTP 402 + EIP-3009 micropayment), and the final signature always stays with your user.

| Step        | Tool                      | Price  | Returns                                                                             |
| ----------- | ------------------------- | ------ | ----------------------------------------------------------------------------------- |
| 1. Decide   | `barker_yield_advisor`    | \$0.03 | Ranked pool picks with data-derived reasons & risk flags                            |
| 2. Discover | `barker_executable_pools` | \$0.01 | Vaults your agent can act on — every row is quotable                                |
| 3. Quote    | `barker_execution_quote`  | \$0.05 | An unsigned transaction `{chainId, to, data, value}` + route + risk + approval info |
| 4. Execute  | *(your wallet)*           | gas    | You sign & broadcast. Vault shares arrive at the signer address                     |

## Non-custodial guarantees

* **Barker never broadcasts and never holds funds.** `barker_execution_quote` sells a transaction; executing it is entirely yours.
* **Shares always go to the signer.** `receiver` is not a parameter — the deposit calldata hard-binds `receiver = signer_address`.
* **What you see is what you sign.** For the `self` adapter (direct ERC4626), the response includes `calldata_amount_base_units` — the amount actually encoded in calldata — so your agent can verify byte-level intent before asking anyone to sign.
* **Same-chain only.** Quotes use the `self` (direct ERC4626) and `portals` (same-chain zap) adapters. Cross-chain routing is not offered on this surface.
* **Quote-only, stateless.** Nothing is stored on Barker's side; a quote expires (`quote_expires_at`) and simply gets re-bought.

## Calling the tools

Every tool answers `GET https://mcp.barker.money/<tool>?<params>` with **HTTP 402** and a `payment-required` header. Your agent signs an EIP-3009 `transferWithAuthorization` for the quoted price (USDT0 on X Layer, or USDC on Base/Ethereum/Polygon/Arbitrum), retries with a `PAYMENT-SIGNATURE` header, and gets the JSON body. Facilitators from OKX, Coinbase CDP, and Circle settle the payment on-chain — your agent never needs gas on the payment chain.

### `barker_executable_pools` — \$0.01

```
GET /barker_executable_pools?asset=usdc&chain=base&action=deposit&limit=20
```

Every parameter is optional — call it with no arguments to get the top executable pools
across all assets. `asset` is matched case-insensitively.

Returns pools filtered to **guaranteed-quotable** rows: capability status `supported`, live deposit capacity (`is_full`), adapters restricted to the self-sign surface (`self` / `portals`), APY (decimal unit: `0.05` = 5%) and TVL. If a pool is listed here, `barker_execution_quote` will price it.

### `barker_execution_quote` — \$0.05

```
GET /barker_execution_quote?pool_uid=<uid>&action=deposit&adapter=self
    &amount_base_units=1000000&signer_address=0xYourUser
```

| Param                | Notes                                                                                                                                                                                                                                                                                                                                                                                                 |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pool_uid`           | Either the exact string from `barker_executable_pools` **or** the vault contract address (`0x` + 40 hex) — if you already know the vault, quote directly with no discovery call. Both are matched exactly; partial names and keywords are rejected with `POOL_NOT_FOUND`, because this is a money path and Barker never guesses the pool. Pass the **vault** contract, not the underlying asset token |
| `chain_id`           | Optional. Only needed when a vault address is deployed at the same address on several chains (e.g. Aave aTokens)                                                                                                                                                                                                                                                                                      |
| `action`             | `deposit` or `redeem` (redeem moves only the signer's own shares, back to the signer)                                                                                                                                                                                                                                                                                                                 |
| `amount_base_units`  | Integer string in token decimals — `1000000` = 1 USDC                                                                                                                                                                                                                                                                                                                                                 |
| `signer_address`     | The EVM address that will sign **and** receive shares. Required                                                                                                                                                                                                                                                                                                                                       |
| `adapter`            | Optional; pin `self` for byte-decodable ERC4626 calldata                                                                                                                                                                                                                                                                                                                                              |
| `from_token_address` | Required only when the vault has multiple underlying tokens                                                                                                                                                                                                                                                                                                                                           |

The response carries `quote.transaction_request` (`chainId`, `to`, `data`, `value`), `approval_required` / `approval_spender` / `exact_approval_only`, gas & output estimates, and `risk_report`. Approve **exactly** the deposit amount, never unlimited.

Business errors come back with machine-readable codes your agent can branch on: `VAULT_FULL`, `MAX_DEPOSIT_EXCEEDED`, `UNSUPPORTED_ACTION`, `ADAPTER_NOT_ALLOWED`, `INVALID_INPUT`, `POOL_NOT_FOUND`, `POOL_AMBIGUOUS`, and others. Every 4xx carries an actionable `error.details` — missing params are listed in full on the first try, and a `POOL_NOT_FOUND` includes currently quotable `example_pool_uids`.

When one contract hosts several distinct products (Pendle `PT` vs `LP`, for example), quoting by address returns `409 POOL_AMBIGUOUS` with the exact candidates rather than a guess — pick one and re-send:

```json theme={null}
{"error":{"code":"POOL_AMBIGUOUS","details":{"candidates":[
  {"pool_uid":"pendle_ethereum_pt-apyusd-27aug2026_0x30bb9ee8","chain_id":1,"pool_name":"Pendle PT PT-apyUSD-27AUG2026"},
  {"pool_uid":"pendle_ethereum_lp-apyusd-27aug2026_0x30bb9ee8","chain_id":1,"pool_name":"Pendle LP APYUSD 27AUG2026"}]}}}
```

All `4xx` responses skip settlement — a rejected call costs you nothing, so it is safe to retry after fixing the request.

## Reference client

A complete working buyer — pay → quote → verify → sign → broadcast → confirm shares, \~200 lines, `viem` as the only dependency:

```bash theme={null}
git clone https://github.com/YBSbarker/barker-stablecoin-skills
cd barker-stablecoin-skills && npm i viem
read -rs PRIVATE_KEY && export PRIVATE_KEY
node examples/x402-execution-buyer.mjs
unset PRIVATE_KEY
```

Copy its two safety checks into your own agent: calldata-amount verification and signer echo. They are the difference between "signing a bought transaction" and "signing blind".

## Rate limits & fair use

Paid callers get 600 requests/min per payer across all tools; `barker_execution_quote` is additionally capped (default 60/min per payer) because each quote performs live on-chain reads. Sustained higher volume: reach out — [partner@barker.money](mailto:partner@barker.money).