Source URL: https://mag3nt.com/skill.md Title: mag3nt API - Agent Skills Guide --- name: mag3nt version: 0.6.0 description: Issue pre-funded payment credentials for autonomous AI agents. One card pays across x402, AP2, and MPP, settling in USDC on Base, Ethereum, Polygon, Arbitrum, Solana, and Tempo. homepage: https://mag3nt.com user-invocable: true metadata: {"category":"finance","primaryEnv":"MAG3NT_API_KEY","requires":{"env":["MAG3NT_API_KEY"]}} --- ``` MAG3NT API QUICK REFERENCE v0.6.0 Base: https://api.mag3nt.com Auth: Authorization: Bearer (key prefix: mag3nt_live_) Get a key: https://mag3nt.com -> Developer -> Generate API Key Docs: This file is canonical. Full reference: https://docs.mag3nt.com What mag3nt does: issues pre-funded credentials ("cards") that let an agent pay any x402, AP2, or MPP endpoint. One card, multiple protocols. Settlement is in USDC on Base / Ethereum / Polygon / Arbitrum / Solana / Tempo. Issue & manage cards: POST /api/issue/bulk -> issue many pre-funded cards in one request (Idempotency-Key required) POST /api/issue -> issue a single pre-funded card GET /api/cards -> list your cards GET /api/cards/:id/transactions -> a card's transaction history POST /api/cards/:id/freeze -> freeze a card POST /api/cards/:id/unfreeze -> unfreeze a card POST /api/cards/:id/claim -> reclaim remaining balance from an expired card Pay with a card (outbound): POST /api/pay -> pay any x402 / AP2 / MPP endpoint; auto-detects protocol and settles on-chain Get paid (inbound, pay links): POST /api/paylinks -> create a shareable / agent-ready payment link GET /api/pay/:code/prepare -> discover payment requirements for a link (public, no auth) POST /api/pay/:code/settle -> submit on-chain proof to settle a link (public) AP2 (Agent Payments Protocol): GET /api/ap2/instruments -> list a card's payment instruments POST /api/ap2/mandate -> issue a Payment Mandate (SD-JWT) POST /api/ap2/receipt -> process a Payment Receipt GET /api/ap2/.well-known/jwks.json -> public verification keys Developer keys & webhooks: POST /api/keys/validate -> verify the current API key POST /api/webhooks -> register a signed payment.settled webhook (HMAC-SHA256) Rules: requests are JSON. Authenticate every call with Bearer . Errors: HTTP status + JSON { "error": "message" }. ``` # mag3nt API - Agent Skills Guide This skill is doc-only. There is no local CLI. It documents the public mag3nt REST API for issuing and spending agent payment credentials. ## What you can do with mag3nt 1. **Issue pre-funded cards** for agents, individually or in bulk. Each card is scoped to a spend limit, optional expiry, optional merchant-category (MCC) restrictions, and can be single-use. 2. **Pay any agentic-commerce endpoint** with one card. `POST /api/pay` auto-detects whether the target speaks x402, AP2, or MPP, prices the request, and settles in USDC on-chain. 3. **Get paid** by creating pay links that agents and humans can settle on-chain, then reconcile automatically. 4. **Receive `payment.settled` webhooks** so a seller backend can release goods or services the moment a payment confirms, without mag3nt holding the seller's upstream API key. The core idea: a mag3nt card is a protocol-agnostic spending credential. You fund it once, then an agent uses it across x402, AP2, and MPP without you re-wiring anything per protocol. ## Base URL & Auth - Base URL: `https://api.mag3nt.com` - Auth header: `Authorization: Bearer ` - Content-Type: `application/json` API keys carry the `mag3nt_live_` prefix and are created from the dashboard: open `https://mag3nt.com`, go to the **Developer** tab, and choose **Generate API Key**. The full key is shown once at creation, so store it securely. Quick env setup: ```bash export MAG3NT_API_URL="https://api.mag3nt.com" export MAG3NT_API_KEY="mag3nt_live_..." # from the Developer tab ``` Validate the key before you rely on it: ```bash curl -sS -X POST "$MAG3NT_API_URL/api/keys/validate" \ -H "Authorization: Bearer $MAG3NT_API_KEY" \ -H "Content-Type: application/json" ``` Returns `{ "valid": true, "wallet_address": "0x...", "authenticated_at": "..." }`. ## Identifiers - Card IDs use the `mag3nt_` prefix (legacy cards may use `sx_`; both remain valid). - Card tokens use the `tok_` prefix. The token is the bearer secret an agent presents when spending a card. Treat it like a password. - Supported networks (CAIP-2): `eip155:8453` (Base), `eip155:1` (Ethereum), `eip155:137` (Polygon), `eip155:42161` (Arbitrum), `eip155:4217` (Tempo), `solana:mainnet`. Settlement asset is USDC. ## Core flow 1: Issue pre-funded cards ### Bulk issue (recommended for fleets) `POST /api/issue/bulk` issues many cards in one atomic request. An `Idempotency-Key` header is required so a retry never double-issues. ```bash curl -sS -X POST "$MAG3NT_API_URL/api/issue/bulk" \ -H "Authorization: Bearer $MAG3NT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "network": "eip155:8453", "asset": "USDC", "cards": [ { "purpose": "Research Agent", "amount": 25 }, { "purpose": "Trading Bot", "amount": 50 } ] }' ``` - `network` (optional, defaults to `eip155:8453`), `asset` (optional, defaults to `USDC`). - `cards`: array of `{ "purpose": string, "amount": number }`. Maximum 500 per request. Each `amount` must be greater than 0. - Returns the created cards, each with its `id` (`mag3nt_...`) and `token` (`tok_...`). ### Single issue `POST /api/issue` issues one card and accepts finer-grained controls. ```bash curl -sS -X POST "$MAG3NT_API_URL/api/issue" \ -H "Authorization: Bearer $MAG3NT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "purpose": "Data subscription", "amount": 20, "network": "eip155:8453", "asset": "USDC", "expires_in": 720, "single_use": false }' ``` - `purpose` and `amount` are required. - `expires_in`: lifetime in hours (omit or `0` for no expiry). - `mcc_locks`: optional comma-separated merchant category codes to restrict spend. - `single_use`: optional boolean for one-shot credentials. ## Core flow 2: Pay any endpoint with a card `POST /api/pay` is the universal outbound payment call. Give it a card and a target URL. mag3nt fetches the URL, reads the 402 / mandate / MPP challenge, prices it against the card limit, settles in USDC on-chain, and returns the resource. ```bash curl -sS -X POST "$MAG3NT_API_URL/api/pay" \ -H "Content-Type: application/json" \ -d '{ "card_id": "mag3nt_...", "card_token": "tok_...", "url": "https://api.example.com/x402/resource" }' ``` - `card_id` and `card_token` are required. - `url` is the protected endpoint to pay and fetch. The same call works whether the endpoint speaks x402, AP2, or MPP. - Optional: `method`, `headers`, `body` to forward to the target endpoint. The card token authorizes the spend, so this endpoint does not need the API key. Only share `card_token` with the agent that is meant to spend that specific card. ## Core flow 3: Get paid with pay links Create a link an agent or a human can pay. The link is agent-ready: it advertises its payment requirements over a public `prepare` endpoint, then accepts on-chain settlement proof. ```bash # 1. Create a pay link bound to one of your cards curl -sS -X POST "$MAG3NT_API_URL/api/paylinks" \ -H "Authorization: Bearer $MAG3NT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "card_id": "mag3nt_...", "amount": 5, "memo": "API access", "accepted_protocols": ["x402", "ap2", "mpp"] }' # 2. A payer discovers requirements (public, no auth) curl -sS "$MAG3NT_API_URL/api/pay//prepare" # 3. The payer sends USDC on-chain, then submits proof (public) curl -sS -X POST "$MAG3NT_API_URL/api/pay//settle" \ -H "Content-Type: application/json" \ -d '{ "protocol": "x402", "tx_hash": "0x...", "from_address": "0x...", "amount": 5 }' ``` - `card_id` is the only required field when creating a link. Optional: `amount` (omit for "any amount"), `memo`, `type`, `max_uses`, `expires_in`, `network`, `asset`, `accepted_protocols`. - Settlement is verified on-chain and replay-protected (a `tx_hash` settles at most once). ## Core flow 4: payment.settled webhooks (for sellers) Register a webhook to be notified the instant a payment settles, so your backend can release goods or unlock a service. mag3nt signs every delivery with HMAC-SHA256 using a per-endpoint secret (prefix `whsec_`) shown once at creation. ```bash curl -sS -X POST "$MAG3NT_API_URL/api/webhooks" \ -H "Authorization: Bearer $MAG3NT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://your-backend.example.com/mag3nt/webhook" }' ``` Verify each delivery before trusting it. Compute HMAC-SHA256 over the raw request body using your `whsec_` secret and compare it (constant-time) to the signature header. ```js import { createHmac, timingSafeEqual } from "node:crypto"; function verify(rawBody, signatureHeader, secret) { const expected = createHmac("sha256", secret).update(rawBody).digest("hex"); const a = Buffer.from(expected); const b = Buffer.from(signatureHeader || ""); return a.length === b.length && timingSafeEqual(a, b); } ``` ## API Endpoints Reference | Endpoint | Method | Path | Notes | |----------|--------|------|-------| | Bulk issue cards | POST | `/api/issue/bulk` | Body: `network`, `asset`, `cards[]` of `{purpose, amount}`. Header: `Idempotency-Key` | | Issue single card | POST | `/api/issue` | Body: `purpose`, `amount`; optional `network`, `asset`, `expires_in`, `mcc_locks`, `single_use` | | List cards | GET | `/api/cards` | Returns `{ cards: [...] }` | | Card transactions | GET | `/api/cards/{id}/transactions` | Per-card spend history | | Freeze card | POST | `/api/cards/{id}/freeze` | Suspends spending | | Unfreeze card | POST | `/api/cards/{id}/unfreeze` | Resumes spending | | Claim expired balance | POST | `/api/cards/{id}/claim` | Returns remaining funds to your balance | | Pay any endpoint | POST | `/api/pay` | Body: `card_id`, `card_token`, `url`; optional `method`, `headers`, `body` | | Create pay link | POST | `/api/paylinks` | Body: `card_id`; optional `amount`, `memo`, `type`, `max_uses`, `expires_in`, `network`, `asset`, `accepted_protocols` | | Prepare pay link | GET | `/api/pay/{code}/prepare` | Public. Returns payment requirements + accepted protocols | | Settle pay link | POST | `/api/pay/{code}/settle` | Public. Body: `protocol`, `tx_hash`, `from_address`, `amount` | | List AP2 instruments | GET | `/api/ap2/instruments` | Query: `card_id`, `card_token` | | Issue AP2 mandate | POST | `/api/ap2/mandate` | Body: `card_id`, `type`, `total` (session) or agent-mode fields | | Process AP2 receipt | POST | `/api/ap2/receipt` | Settle against a mandate | | AP2 public keys | GET | `/api/ap2/.well-known/jwks.json` | JWKS for verifying mandates | | Validate API key | POST | `/api/keys/validate` | Returns `{ valid, wallet_address }` | | Register webhook | POST | `/api/webhooks` | Body: `url`. Returns a `whsec_` secret once | ## Fees Outbound settlement fee is 0.5% + $0.001 USDC per transaction. Network withdrawal fees are flat per chain and configurable. There are no per-transaction overrides. ## Error Responses Errors return JSON with an HTTP status: ```json { "error": "message" } ``` | Status | Meaning | Common cause | |--------|---------|--------------| | 400 | Bad Request | Missing or invalid fields | | 401 | Unauthorized | Missing or invalid API key | | 403 | Forbidden | Insufficient balance, frozen card, or permission denied | | 404 | Not Found | Resource does not exist | | 409 | Conflict | Duplicate action | | 429 | Rate Limited | Too many requests, back off and retry | | 500 | Server Error | Transient, retry later | ## Security - Never share your API key or a card token in logs, posts, or screenshots. - A card token (`tok_`) authorizes spending on that card. Scope each agent to its own card. - Rotate a key from the Developer tab if you suspect exposure. - Verify webhook signatures before acting on a delivery. --- Built for agents.