Metadata-Version: 2.4
Name: oceanalt-mcp
Version: 0.1.3
Summary: OceanAlt pre-payment check for AI agents: allow, review or decline before your agent pays. Includes an Amazon Bedrock AgentCore pre_sign_policy.
Author-email: OceanAlt <business@oceanalt.com>
License: MIT
Project-URL: Homepage, https://oceanalt.com
Project-URL: Documentation, https://oceanalt.com/en/api-docs
Keywords: oceanalt,ai-agents,agent-payments,x402,pre-payment,mcp,agentcore
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# oceanalt-mcp

OceanAlt pre-payment check for AI agents: before your agent pays, ask whether the payment should proceed. Returns `allow`, `review` or `decline` with reasons and evidence.

```python
from oceanalt_mcp import decide
r = decide("0xd90e2f925DA726b50C4Ed8D0Fb90Ad053324F31b", network="ethereum")
print(r["decision"])  # decline: a known mixer
```

## Amazon Bedrock AgentCore payments

AgentCore calls `pre_sign_policy` before it signs a payment and signs only if the policy returns exactly `True`. Set this policy on the config of every AgentCore payments integration you want gated. Installing or importing this package changes nothing by itself.

Install this version and the SDK for your framework. The pins are the combination this release was verified with; other versions may also work:

```
pip install "oceanalt-mcp==0.1.3" "bedrock-agentcore==1.26.0" "strands-agents==1.64.0"                      # Strands
pip install "oceanalt-mcp==0.1.3" "bedrock-agentcore==1.26.0" "langchain==1.4.10" "langgraph==1.2.20"   # LangGraph
```

This client needs Python 3.8+ and has no third-party dependencies. The AgentCore SDK and the frameworks have their own requirements (Python 3.10+ for the versions verified below).

Strands:

```python
from strands import Agent
from bedrock_agentcore.payments.integrations.strands import AgentCorePaymentsPlugin, AgentCorePaymentsPluginConfig
from oceanalt_mcp import agentcore_pre_sign_policy

config = AgentCorePaymentsPluginConfig(
    payment_manager_arn="arn:aws:...",
    user_id="user-123",
    payment_instrument_id="instrument-456",
    payment_session_id="session-789",
    pre_sign_policy=agentcore_pre_sign_policy,
)
agent = Agent(tools=[...], plugins=[AgentCorePaymentsPlugin(config)])
```

LangGraph (LangChain `create_agent`):

```python
from langchain.agents import create_agent
from bedrock_agentcore.payments.integrations.langgraph import AgentCorePaymentsMiddleware, AgentCorePaymentsConfig
from oceanalt_mcp import agentcore_pre_sign_policy

config = AgentCorePaymentsConfig(payment_manager_arn="arn:aws:...", user_id="user-123",
                                 payment_instrument_id="instrument-456", payment_session_id="session-789",
                                 pre_sign_policy=agentcore_pre_sign_policy)
agent = create_agent(model=..., tools=[...], middleware=[AgentCorePaymentsMiddleware(config)])
```

What the policy checks: the payee address and network of each offer, and nothing else. It does not check the amount, the asset, the merchant's origin or any other payment condition, so `True` means every payee passed this check, not that the whole payment is approved.

How it decides:

- Returns `True` only when the request is an unambiguous x402 v1 request (JSON body, `x402Version` 1) or x402 v2 request (base64 `Payment-Required` header, `x402Version` 2, CAIP-2 networks), and OceanAlt answers `allow` for every payee offered in it.
- Returns `False`, so nothing is signed, for: MPP challenges, a request carrying both v1 and v2 requirements, any entry without a payee or network, a v2 network that is not a valid CAIP-2 id, a duplicate JSON key, base64 that is not strictly valid, a version that does not match, more than 10 offers, a decline or review, a timeout, an HTTP error and any other exception.
- Checks every offered payee, because AgentCore may pick any of them (a conservative choice). An identical (payTo, network) pair is looked up once.
- Each lookup uses an 8-second network timeout. The policy uses a 20-second deadline for accepting lookup results: it returns `False` if the deadline has expired before the final approval check, even if a late lookup would have answered `allow`. Lookup waits use the remaining budget, but parsing and thread scheduling can delay the return. A timed-out lookup may continue in the background; its late result cannot authorize signing. Both values are arguments of the policy (`timeout`, `budget`).
- Requests that name a testnet or an unsupported network are not cleared by this policy.
- Sends each offered payee address and its network to `https://oceanalt.com/api/decide`. Nothing else from the request is sent.
- The free tier needs no key. It has a monthly anonymous allowance and per-IP rate limits; agents behind one shared IP share them. When either is used up the policy returns `False`.

Verified against bedrock-agentcore 1.26.0 (strands-agents 1.64.0, langchain 1.4.10, langgraph 1.2.20) with a mock signer: 0 signer calls on decline, review, unreadable, ambiguous or MPP input, timeout, exception and an allow that arrives after the budget; 1 on allow. Not yet tested end to end in a live AWS account.

Free to use. Docs: https://oceanalt.com/en/api-docs · Hosted MCP server: https://oceanalt.com/api/mcp
