Bridle Documentation
Bridle is an on-chain safety harness that lets AI agents pay for APIs, compute, and services across blockchains without ever touching or holding a private key.
Zero Keys
Your agent never handles private keys. Prompt injection cannot drain your funds.
Hard Contract Rules
You set spending limits once on NEAR. The contract strictly validates every transfer.
Multi-Chain Signing
Executes transfers to Base (EVM) using NEAR Chain Signatures MPC, and pays native NEAR directly.
Get Started
3-Minute Quickstart
Follow these 4 simple steps to connect an AI agent to Bridle on NEAR Testnet:
Connect your owner wallet
Open the Bridle App and connect your testnet NEAR account (e.g. yourname.testnet).
Create a spending rule for your AI agent
Navigate to New Rule. Enter your agent's NEAR address (e.g. agent.testnet), specify approved recipient addresses on Base or NEAR, and choose daily and per-payment caps (e.g. $25 per payment, $50 per day).
Deposit security funds (Agent bond)
The agent deposits testnet NEAR as a security deposit (e.g. 1 NEAR). This deposit stays locked to guarantee honest behavior and can be withdrawn whenever the rule is retired.
Send a test payment from the agent
Use our Test Console or the Python / TypeScript SDK code below. The contract validates all limits, pausing or approving transactions in real time.
Vocabulary
Core Concepts in Plain English
| Concept | What it means | Why it matters |
|---|---|---|
| Spending Rule (Mandate) | The boundary signed by the owner defining max spends and allowed recipients. | The contract blocks any request outside these bounds. |
| Review Delay (Challenge Window) | A short cooling period (e.g. 10 minutes) for payments exceeding a pause threshold. | Gives you time to review or cancel payments before they finalize. |
| Security Deposit (Bond) | Testnet NEAR deposited by the agent to enable high-value proposals. | Slashed if the agent acts maliciously, rewarding the reviewer who caught it. |
| Reviewer (Watcher) | Any community participant who inspects pending paused transactions. | Earns 40% of the agent's security deposit for discovering bad behavior. |
| Emergency Freeze (Revoke) | A one-click action that immediately stops the agent from making any further payments. | Executes instantly on the blockchain to protect all funds. |
Architecture
How AI Agents Spend (Zero Private Keys)
When an AI agent runs autonomously, giving it a raw private key is a dangerous security liability. A single prompt injection or bug can siphon all stored assets.
The Bridle Security Model
1. Agent Proposes
The agent submits only 4 simple fields: chain, asset, amount, and recipient. It never builds transaction calldata.
2. Contract Evaluates
The NEAR smart contract checks daily caps, per-transaction caps, allowlists, and cooling delays. Reverts if violated.
3. MPC Signatures
NEAR Chain Signatures threshold network signs the raw transaction bytes and broadcasts them to Base.
Developer Integration
Agent Tool Schema & Code Examples
Provide this tool definition to OpenAI models, Claude, LangChain, or custom agents. The agent uses function calling to propose payments safely.
{
"name": "propose_payment",
"description": "Propose a cross-chain payment. The Bridle smart contract verifies spending rules before signing.",
"parameters": {
"type": "object",
"properties": {
"mandate_id": {
"type": "integer",
"description": "The ID of the active spending rule created by your owner"
},
"chain": {
"type": "string",
"enum": ["Base", "Near"],
"description": "The destination blockchain network"
},
"asset": {
"type": "string",
"enum": ["USDC"],
"description": "The currency to send (testnet USDC)"
},
"amount": {
"type": "string",
"description": "Amount in token smallest units (1 USDC = 1000000)"
},
"recipient": {
"type": "string",
"description": "Approved recipient wallet address on the destination chain"
}
},
"required": ["mandate_id", "chain", "asset", "amount", "recipient"]
}
}Rule Enforcement
Spending Limits & Allowed Recipients
Every spending rule defines boundaries that are enforced by smart contract logic:
Per-Payment Limit
The maximum amount the agent can send in a single transaction (e.g. $25 USDC). Any proposal requesting more than this amount is instantly rejected by the smart contract.
Daily Limit
The maximum cumulative amount the agent can spend in a single day (e.g. $50 USDC). The internal counter automatically resets at 00:00 UTC daily.
Pause Payments Above Threshold
Amounts under this threshold execute immediately. Amounts above this threshold enter a safety review delay, requiring the agent's security deposit and giving you time to review.
Approved Recipients Only
The agent can only send money to addresses on your approved recipient list. Any request to an unknown or unlisted address is stopped and logged immediately.
Asymmetric Security: Delayed Loosening, Instant Tightening
To protect your funds against compromised sessions or stolen credentials, Bridle implements asymmetric rule changes:
- Tightening limits or stopping a rule takes effect immediately: Lowering caps, shortening pause thresholds, or freezing a rule happens in the exact block you sign.
- Loosening limits requires a safety delay: Raising a spending cap or adding new recipients is queued for one challenge window delay. This ensures an attacker cannot steal access and flash-drain funds before you notice.
Safety System
Review Delay, Security Deposits & Community Watch
Bridle pairs human oversight with economic incentives so payments can run safely without requiring human intervention on every single micro-payment.
Game-Theoretic Reviewer Economics
Anyone in the community can monitor paused transactions on the Watch page. To prevent false alarms and self-dealing attacks, the economics are strictly balanced:
Reporting Fee
A reviewer stakes 10% of the agent bond to flag a payment. This stops spamming of false flags.
Owner Confirms Flag
The agent's bond is slashed: 40% to reviewer, 30% to owner, and 30% burned.
Dismissed Flag
If the owner dismisses a false report, the reviewer's stake is forfeited directly to the agent.
Fail-Closed Safety Guarantee
If a payment is flagged as suspicious and the owner takes no action, the payment expires unexecuted. The system always prefers a missed payment over an unauthorized transfer.
Emergency Freeze & One-Click Veto
As the owner, you always hold ultimate authority:
You can cancel any paused payment before the review delay expires with zero penalty.
Freezing a rule immediately and permanently revokes the agent's ability to request any further transactions.
API Reference
Smart Contract Reference (NEAR Testnet)
Owner Methods
| Method | Arguments | Description |
|---|---|---|
| create_mandate | agent, chains, assets, recipients, per_tx_cap, daily_cap, cooling_threshold, challenge_window, bond, expiry | Creates a new spending rule with caps and allowlists. |
| veto | proposal_id | Cancels a pending payment proposal before its window finishes. |
| resolve_flag | proposal_id, confirmed (bool) | Confirms suspicious activity (slashes agent) or dismisses it. |
| update_limits | mandate_id, per_tx_cap, daily_cap, cooling_threshold, challenge_window | Applies tighter limits now, queues looser limits. |
| revoke | mandate_id | Immediately stops the spending rule forever. |
Agent Methods
| Method | Arguments | Description |
|---|---|---|
| post_bond | mandate_id (attached deposit in NEAR) | Deposits the required security deposit to activate the rule. |
| propose_payment | mandate_id, chain, asset, amount, recipient | Requests a payment. Evaluated against all spending rules. |
| withdraw_bond | mandate_id | Withdraws security deposit when a mandate is expired or revoked. |
Reviewer & Public Methods
| Method | Caller | Description |
|---|---|---|
| flag(proposal_id) | Any Watcher | Flags a pending payment as suspicious (requires 10% bond stake). |
| execute(proposal_id) | Anyone | Clears a proposal after its review delay successfully expires. |
| expire_flag(proposal_id) | Anyone | Safely closes an unanswered flag after the owner response window. |
| apply_pending_limits | Anyone | Applies queued limit increases once their delay has passed. |
| timeout_signing(proposal_id) | Anyone | Expires any proposal stuck in Signing for over 1 hour to release agent bond. |
| report_failure(proposal_id, reason) | Executor | Reports execution failure on destination chain, cancelling proposal and refunding budget. |
Read-Only View Queries (No Gas / No Wallet Required)
| View Function | Parameters | Returns |
|---|---|---|
| get_mandate | { mandate_id: number } | Mandate object or null |
| list_mandates_for | { account_id: string, from, limit } | List of Mandates |
| get_proposal | { proposal_id: number } | Proposal details & status |
| list_proposals | { mandate_id, from, limit } | Array of Proposals |
Status & Limits
What works today, and what does not.
Bridle claims only what it does. Anything that runs on a testnet, is planned, or rests on a trust assumption is labelled here. Plans are on the roadmap.
Works today
- A NEAR contract that enforces recipients, caps, review thresholds and a veto.
- Native NEAR payments from a balance the owner funds and can take back.
- USDC on Base Sepolia through NEAR Chain Signatures, verified end to end.
- Payment-request links and one-click Pay for native NEAR.
- bridle-mcp on npm: read-only without a key, proposals with a restricted one.
Not yet, or not claimed
- Solana signing. It is planned, not built.
- Mainnet. Everything runs on testnets with test assets.
- A finished audit. The contract is still being audited. See audit progress below.
- Arbitrary contract calls. Every payment is a plain transfer.
- Mixed assets in one rule. A NEAR rule is NEAR-only, and caps are set in that asset's units.
What you still trust
Bridle removes the agent's access to your keys. It does not remove every trust assumption.
- For payments on other chains, the NEAR Chain Signatures network signs the transaction, and Bridle does not remove that trust.
- An executor account broadcasts the signed transaction. It cannot change the payment, but it can delay it.
- The contract is the only enforcement point, and its audit is not finished. It is done by the author, with no paid auditor.
- The approved recipients are fixed when you sign the rule. Paying a new recipient needs a new rule.
Audit progress
The contract is being audited by its author, alone and in the open. No audit firm is involved and no one is being paid for it. That is a weaker assurance than an independent audit, and you should weigh it that way. Findings and the commits that fix them will be listed here as they are found.
- Contract test suite: 32 tests, all passing, including native NEAR paymentsDone
- Negative checks on testnet: the cases that should be refused were refusedDone
- Mixed-asset gap found and closed: one rule can no longer mix NEAR with other chainsDone
- Line-by-line review of the contractNext
- Review of the signing path and the executorNext
- Publish findings and the fixes hereNext
Troubleshooting
Common Error Messages & Fixes
"recipient not in allowlist"
Cause: The agent attempted to pay an address not registered in the spending rule's approved list.
Fix: Add the recipient to your approved list when editing the spending rule.
"per_tx_cap exceeded"
Cause: The proposed payment amount is higher than the max allowed per payment.
Fix: Lower the payment amount or update the spending limit from the rule details screen.
"daily_cap exceeded"
Cause: Total spending today has reached the 24-hour limit.
Fix: Wait until 00:00 UTC for the counter to reset, or increase the daily cap.
"insufficient agent bond posted"
Cause: Over-threshold payments require a security deposit before requests are accepted.
Fix: Switch to the agent wallet account and call post_bond (available via the test console banner).
Frequently Asked Questions
Got Questions? We Have Answers.
Can my AI agent steal my funds if it gets hacked or prompt injected?
No. The AI agent never receives private keys. All payment requests pass through the smart contract on NEAR, which checks strict limits on every proposal. An agent cannot create arbitrary transactions, alter destinations, or exceed caps.
What happens if I am asleep when a suspicious payment is requested?
If an over-threshold payment is flagged as suspicious by a community reviewer and you take no action, it automatically expires unexecuted. Funds remain safely in your account. The system fails closed.
Why are payments settled in USDC instead of volatile tokens?
Stablecoins allow precise arithmetic in integer units without relying on volatile price oracles that could be manipulated. In future releases, multi-asset options will be introduced.
Which blockchains are supported?
Bridle coordinates payments on NEAR Testnet and signs transactions for Base Sepolia (EVM) using NEAR Chain Signatures MPC. Solana is planned.
Ready to test your agent?
Launch the app, create your first spending rule, and run a test payment in under 2 minutes.