Intent API & SDK

Use the agent's credential

Available today The repository includes a small TypeScript client. The public API uses HTTPS at https://api.demo.permixa.io and an agent Bearer credential. In the hosted pilot, the local connector uses a dedicated connection receipt to acquire short-lived agent tokens; this is not a replaceable dashboard API key.

Keep the credential in a protected runtime environment or secret manager. Do not embed it in frontend code, URLs, source control or prompts. Dashboard administrator sessions and Signer credentials are separate and are not interchangeable.

Supported agent methods

The SDK source is sdk/src/client.ts, exported through sdk/src/index.ts. It is part of the repository; this guide does not imply a published npm package.

Start with a read-only call

After building the repository, this Node.js example can run from its root. Supply the credential through your local secret environment, not as a literal in the script.

import { PermixaClient } from "./dist/sdk/src/index.js";

const agentToken = process.env.PERMIXA_AGENT_TOKEN;
if (!agentToken) throw new Error("Agent credential is not configured");

const client = new PermixaClient({
  baseUrl: "https://api.demo.permixa.io",
  agentToken,
});
const budget = await client.getBudget();
console.log(budget);

A purchase request

The following is an illustrative request body, not a live merchant or an automatically executed example. Use only a configured supported resource and an approved test amount.

{
  "protocol": "x402",
  "resource": "https://vendor.example/report",
  "purpose": "Purchase an approved research report",
  "max_amount_usd": "0.01"
}

Send it through trusted merchant discovery with submitHttpPayment(request, key) or POST /v1/http-payments, Content-Type: application/json, the agent's Authorization header, and an Idempotency-Key for this one logical request. The SDK adds these headers. It exposes no raw signing or treasury-administration method.

Idempotency and uncertain outcomes

Keep the same idempotency key and identical body for the same logical request; changed content with that key is a conflict. This is not permission to start another financial operation after uncertainty. Query the existing intent/transaction and preserve its identity. If a timeout leaves you without an intent ID, use getIntentByIdempotencyKey(key) with the original key (URL-encoded in the API path). A missing result or outage is inconclusive, not proof that no payment occurred. Do not create a replacement payment.

Keys must start with an alphanumeric character and use only letters, digits, period, underscore, colon or hyphen, up to 128 characters. Never put secrets into keys. Receipt/submission alone does not prove final settlement or resource delivery.

Connect through local MCP

Available today Run the local stdio connector alongside your agent. It talks to the existing testnet API; a hosted MCP server is not currently provided. The connector does not connect directly to your wallet.

1. In the demo app, open Agents and follow its connection instructions. Hosted pilot access uses a dedicated agent connection with assisted setup; recover the saved connection rather than trying to replace an API key. Self-managed API keys remain a separate supported mode.
2. Ask your workspace operator for the reviewed private package and matching checksum. Operators can build it with npm run mcp:package:smoke or use the repository CI artifact. It is not published to the public npm registry.
3. Use Node.js 22.20 or newer. Follow the README included with the package to install it in your agent workspace. Configure your client using the package README: either a private dedicated connection receipt and exact organization/agent binding, or an agent token supplied privately. Launch the connector by its absolute path. No wallet keys, Signer credentials or administrator sessions belong here.

Start without spending

Connector 0.2.0 adds permixa_connection_status. Ask “Is my purchase tool enabled, and which resources are configured?” This local check reports connector settings without accessing a credential or contacting the API. It explicitly leaves authentication, Signer health, funding, merchant policy and spending permission unverified. Follow it with a budget check for agent API access; neither result alone proves a purchase can execute.

The default tools read your agent's budget, look up an intent, recover its ID using the original idempotency key, and follow a transaction. Ask: “What is my remaining budget?” or “What happened to my existing request?” The budget is a cloud reference-USD allowance, not a wallet balance or permission to spend.

• permixa_budget
• permixa_intent_status
• permixa_intent_lookup
• permixa_transaction_status

Enable purchases deliberately

Purchases are off by default. The configured pilot exposes permixa_purchase for approved x402 resources and permixa_purchase_result when a customer-local results directory is configured. Its installed per-request limit is 0.01 test USD; the package maximum below is a ceiling, not the pilot allowance. An operator must explicitly enable them and configure exact approved resource URLs. The connector caps a purchase at 0.25 reference USD; agent budgets and independent customer-local atomic limits still apply. The separate worker performs the approved purchase and records delivery. DELIVERED means content arrived; SETTLED requires independent payment evidence. Direct USDC and L402 are not enabled by these MCP tools. There are no raw signing, transfers, treasury administration or policy-changing tools.

Operators should follow the repository guide docs/operations/agent-mcp-testnet.md before a live attempt. For users, start with the testnet demo guide and recovery guidance. An authorized or submitted request is not proof of settlement or resource delivery.