# Create a spending mandate for recurring AP2 payments Source: https://docs.mag3nt.com/api-reference/ap2/create-a-spending-mandate-for-recurring-ap2-payments /openapi.yaml post /api/ap2/mandate # Execute a payment against an AP2 mandate Source: https://docs.mag3nt.com/api-reference/ap2/execute-a-payment-against-an-ap2-mandate /openapi.yaml post /api/ap2/execute # Get the default agent card for AP2 payments Source: https://docs.mag3nt.com/api-reference/ap2/get-the-default-agent-card-for-ap2-payments /openapi.yaml get /api/ap2/agent-card # List available payment methods for AP2 Source: https://docs.mag3nt.com/api-reference/ap2/list-available-payment-methods-for-ap2 /openapi.yaml post /api/ap2/payment-methods # List mandates for a card Source: https://docs.mag3nt.com/api-reference/ap2/list-mandates-for-a-card /openapi.yaml get /api/ap2/mandates/{card_id} # Settle a pay link with a closed AP2 Payment Mandate Source: https://docs.mag3nt.com/api-reference/ap2/settle-a-pay-link-with-a-closed-ap2-payment-mandate /openapi.yaml post /api/ap2/settle Settles a mag3nt pay link by consuming a closed AP2 Payment Mandate (`mandate.payment.1`). The mandate is verified for signature, expiry, and payee scoping against the link; if an open mandate is supplied, the open→closed chain is re-verified. The payer card named by the mandate is authenticated via its card token, then the payer card is debited and the link credited atomically. Idempotent on the mandate `jti` (replay-safe). # Cancel a billing agreement Source: https://docs.mag3nt.com/api-reference/billing/cancel-a-billing-agreement /openapi.yaml post /api/billing/agreements/{id}/cancel # Create a recurring billing agreement from an AP2 open mandate Source: https://docs.mag3nt.com/api-reference/billing/create-a-recurring-billing-agreement-from-an-ap2-open-mandate /openapi.yaml post /api/billing/agreements Consent is an AP2 open mandate carrying a payment.recurring constraint. Provide exactly one of pay_link_code (merchant billing) or plan_ref (platform plans, e.g. membership). Interval agreements charge period 1 inline unless defer_first_charge is set. # Get a billing agreement and its charge history Source: https://docs.mag3nt.com/api-reference/billing/get-a-billing-agreement-and-its-charge-history /openapi.yaml get /api/billing/agreements/{id} # List your billing agreements Source: https://docs.mag3nt.com/api-reference/billing/list-your-billing-agreements /openapi.yaml get /api/billing/agreements # Add funds to an existing card from treasury balance Source: https://docs.mag3nt.com/api-reference/cards/add-funds-to-an-existing-card-from-treasury-balance /openapi.yaml post /api/cards/{id}/fund Top up an ACTIVE card by allocating additional USDC from your treasury balance. The allocation is atomic: insufficient balance returns 403. # Close a card Source: https://docs.mag3nt.com/api-reference/cards/close-a-card /openapi.yaml post /api/cards/{id}/close Soft-closes a card when it has zero remaining balance and no pending transactions, open payment streams, or active AP2 mandates. Sweep any remaining funds with POST /api/cards/{id}/claim first. Closed cards are hidden from the wallet UI; history remains in GET /api/transactions. # Freeze a card to block all transactions Source: https://docs.mag3nt.com/api-reference/cards/freeze-a-card-to-block-all-transactions /openapi.yaml post /api/cards/{id}/freeze # Get a credential by id or on-chain holder address Source: https://docs.mag3nt.com/api-reference/cards/get-a-credential-by-id-or-on-chain-holder-address /openapi.yaml get /api/v1/credentials/{ref} Returns verifiable performance plus the on-chain anchor. `ref` may be a credential id or a 0x holder address. # Get just the on-chain anchor for a credential Source: https://docs.mag3nt.com/api-reference/cards/get-just-the-on-chain-anchor-for-a-credential /openapi.yaml get /api/v1/credentials/{ref}/onchain Cheaper than the full resource - holder, CRT, and explorer links only. # Issue a new virtual payment card Source: https://docs.mag3nt.com/api-reference/cards/issue-a-new-virtual-payment-card /openapi.yaml post /api/issue Creates a card backed by your treasury balance. Provide `tx_hash` for UI pay-and-issue flow (card starts as PENDING_FUNDING). Omit `tx_hash` to allocate from pre-funded balance. # Issue multiple cards in a single atomic request Source: https://docs.mag3nt.com/api-reference/cards/issue-multiple-cards-in-a-single-atomic-request /openapi.yaml post /api/issue/bulk Creates up to 1000 cards atomically. All cards are allocated from treasury balance in a single atomic operation. Supports idempotency via header. # List account activity across all cards Source: https://docs.mag3nt.com/api-reference/cards/list-account-activity-across-all-cards /openapi.yaml get /api/transactions Wallet-scoped activity feed spanning every card (including CLOSED). Returns outgoing spends and incoming protocol settlements, each tagged with card_purpose and card_status for attribution. # List all cards for the authenticated wallet Source: https://docs.mag3nt.com/api-reference/cards/list-all-cards-for-the-authenticated-wallet /openapi.yaml get /api/cards # List publicly listed credentials Source: https://docs.mag3nt.com/api-reference/cards/list-publicly-listed-credentials /openapi.yaml get /api/v1/credentials Third-party developer view of credentials with an active marketplace listing. Rate-limited per-minute and metered against your key's monthly quota (X-RateLimit-* / X-Quota-* response headers; 429 = rate exceeded, 402 = quota exceeded). Testnet-funded credentials never surface on a mainnet deployment. # List transactions for a card Source: https://docs.mag3nt.com/api-reference/cards/list-transactions-for-a-card /openapi.yaml get /api/cards/{id}/transactions # Move card funds back to treasury Source: https://docs.mag3nt.com/api-reference/cards/move-card-funds-back-to-treasury /openapi.yaml post /api/cards/{id}/claim Sweeps unspent balance from a card into your treasury (wallet balance). From treasury you can withdraw off-platform via POST /api/withdraw. For EXPIRED cards this always performs a full sweep. For ACTIVE or FROZEN cards, omit `amount` to sweep all available funds, or pass `amount` for a partial claim - the card stays active with the remainder. Pending charges and mandate holds are excluded from the sweepable balance. # Public Credential API root - auth + endpoint directory Source: https://docs.mag3nt.com/api-reference/cards/public-credential-api-root--auth-+-endpoint-directory /openapi.yaml get /api/v1 # Unfreeze a previously frozen card Source: https://docs.mag3nt.com/api-reference/cards/unfreeze-a-previously-frozen-card /openapi.yaml post /api/cards/{id}/unfreeze # Update card spending controls Source: https://docs.mag3nt.com/api-reference/cards/update-card-spending-controls /openapi.yaml patch /api/cards/{id}/controls # Confirm a signed CRT market listing transaction Source: https://docs.mag3nt.com/api-reference/credential-tokens/confirm-a-signed-crt-market-listing-transaction /openapi.yaml post /api/cards/{id}/crt-market/confirm Verifies the listing receipt on-chain (never trusts client-supplied addresses), reads back pool state, and records the market as LISTED. # Get live Uniswap V4 market details for a CRT Source: https://docs.mag3nt.com/api-reference/credential-tokens/get-live-uniswap-v4-market-details-for-a-crt /openapi.yaml get /api/cards/{id}/crt-market Returns pool state read live from-chain (fee tier, liquidity, creator-owed fees) plus any pending auto-vesting-lock calldata. Self-heals the DB row if a listing landed on-chain but the confirm call never completed. # Get the Credential Token (CT) for a credential, if launched Source: https://docs.mag3nt.com/api-reference/credential-tokens/get-the-credential-token-ct-for-a-credential-if-launched /openapi.yaml get /api/cards/{id}/crt Also returns deploy progress, the owner's own MAG3NT launch-fee balance/allowance context, on-chain holder balance of the CRT, and whether tokenizing is currently available on this network. # Get the MAG3NT fee token and current CRT launch fee Source: https://docs.mag3nt.com/api-reference/credential-tokens/get-the-mag3nt-fee-token-and-current-crt-launch-fee /openapi.yaml get /api/mag3nt Also returns the authenticated owner's own on-chain MAG3NT balance (the wallet the launch fee is paid from). # Launch a Credential Token for an owned credential Source: https://docs.mag3nt.com/api-reference/credential-tokens/launch-a-credential-token-for-an-owned-credential /openapi.yaml post /api/cards/{id}/launch-crt Mints a fixed-supply B20 Asset representing a claim on the credential's future revenue. Charges the MAG3NT launch fee from the owner's own wallet (never the credential's holder). One CRT per credential; a second launch returns the existing one. Deploys on-chain synchronously when possible, else leaves it PENDING_DEPLOY for the deploy cron to retry. # List all live CRT Uniswap V4 markets Source: https://docs.mag3nt.com/api-reference/credential-tokens/list-all-live-crt-uniswap-v4-markets /openapi.yaml get /api/crt-markets # Prepare an unsigned Uniswap V4 fair-launch listing for a CRT Source: https://docs.mag3nt.com/api-reference/credential-tokens/prepare-an-unsigned-uniswap-v4-fair-launch-listing-for-a-crt /openapi.yaml post /api/cards/{id}/crt-market/prepare Builds the unsigned calldata to list an already-deployed CRT on Uniswap V4 (Doppler-style fair launch). Mag3nt never signs or custodies liquidity; the creator wallet signs the returned transaction and any required token/WETH approvals. # Record the Sablier vesting lock for a CRT's kept slice Source: https://docs.mag3nt.com/api-reference/credential-tokens/record-the-sablier-vesting-lock-for-a-crts-kept-slice /openapi.yaml post /api/cards/{id}/crt-market/vesting-confirm Automatic completion for an already-live market whose creator kept slice is still un-vested. Verifies the Sablier stream receipt and stores the public stream URL. Not typically called directly by integrators - the client invokes it when it detects a pending lock. # Credit a verified on-chain MAG3NT transfer to your fee meter Source: https://docs.mag3nt.com/api-reference/fees/credit-a-verified-on-chain-mag3nt-transfer-to-your-fee-meter /openapi.yaml post /api/fees/deposit Submits an on-chain MAG3NT transfer to the treasury for verification. Idempotent on tx_hash. Nets off any existing debt automatically. # Get your prepaid MAG3NT fee meter balance Source: https://docs.mag3nt.com/api-reference/fees/get-your-prepaid-mag3nt-fee-meter-balance /openapi.yaml get /api/fees/balance Every settled DIRECT payment above your membership quota debits a flat MAG3NT fee from this prepaid balance. Debits always succeed (an already-verified on-chain payment can never be refused), so the balance can go negative up to debt_floor; past that, pay-link discovery for your DIRECT credentials is withheld until you deposit. # Get on-chain token balance for a wallet address Source: https://docs.mag3nt.com/api-reference/funding/get-on-chain-token-balance-for-a-wallet-address /openapi.yaml get /api/wallet/balance Queries the blockchain directly to return the real-time token balance for a given wallet address on a specific network. Supports EVM and Solana. # Get treasury balance for authenticated wallet Source: https://docs.mag3nt.com/api-reference/funding/get-treasury-balance-for-authenticated-wallet /openapi.yaml get /api/balance # List accepted tokens per network Source: https://docs.mag3nt.com/api-reference/funding/list-accepted-tokens-per-network /openapi.yaml get /api/funding/tokens # Verify an on-chain funding transaction Source: https://docs.mag3nt.com/api-reference/funding/verify-an-on-chain-funding-transaction /openapi.yaml post /api/fund/verify Submit an on-chain transaction hash to credit your treasury balance. The platform verifies the transaction on-chain, confirms the Transfer event matches the treasury address, and atomically credits your balance. Idempotent: re-submitting an already-confirmed tx_hash returns the existing balance without double-crediting. # List every Credential Token balance the wallet holds Source: https://docs.mag3nt.com/api-reference/holdings/list-every-credential-token-balance-the-wallet-holds /openapi.yaml get /api/holdings Scans the deployed CRT universe and reads on-chain balanceOf for the signed-in wallet, so tokens received from another mag3nt account (not tied to a credential you own) are visible too. # Generate a new API key Source: https://docs.mag3nt.com/api-reference/keys/generate-a-new-api-key /openapi.yaml post /api/keys/generate Returns the raw key once. Store it securely: it cannot be retrieved again. # List all API keys for the authenticated wallet Source: https://docs.mag3nt.com/api-reference/keys/list-all-api-keys-for-the-authenticated-wallet /openapi.yaml get /api/keys # Revoke an API key Source: https://docs.mag3nt.com/api-reference/keys/revoke-an-api-key /openapi.yaml delete /api/keys/{hash} # Validate an API key Source: https://docs.mag3nt.com/api-reference/keys/validate-an-api-key /openapi.yaml post /api/keys/validate # Browse open marketplace listings Source: https://docs.mag3nt.com/api-reference/marketplace/browse-open-marketplace-listings /openapi.yaml get /api/listings Public discovery of sellable credentials, enriched with verifiable performance stats. Testnet-funded listings never surface on a mainnet deployment. Supports optional pagination (page + limit) and sorting. # Buy a listed credential Source: https://docs.mag3nt.com/api-reference/marketplace/buy-a-listed-credential /openapi.yaml post /api/listings/{id}/buy Escrows the buyer's USDC card funds, atomically re-keys credential ownership (and its pay links), pays out the seller net of the marketplace take rate, and captures the fee. Any failure after escrow fully unwinds - no half-completed sale, no lost funds. # Cancel your own open listing Source: https://docs.mag3nt.com/api-reference/marketplace/cancel-your-own-open-listing /openapi.yaml post /api/listings/{id}/cancel # Get a single listing (public, works for shared links) Source: https://docs.mag3nt.com/api-reference/marketplace/get-a-single-listing-public-works-for-shared-links /openapi.yaml get /api/listings/{id} Returns the listing regardless of state, so a shared link of a sold/frozen credential still renders truthfully. `sellable` mirrors the exact buy-time gate. # Get the most recent listing for a credential (public) Source: https://docs.mag3nt.com/api-reference/marketplace/get-the-most-recent-listing-for-a-credential-public /openapi.yaml get /api/cards/{id}/listing # List a credential for sale on the marketplace Source: https://docs.mag3nt.com/api-reference/marketplace/list-a-credential-for-sale-on-the-marketplace /openapi.yaml post /api/cards/{id}/list Lists an owned, unencumbered credential for sale. Selling transfers the whole economic account (paylinks, history, delegation) to the buyer atomically against payment. Only USDC settlement is live today. # Cancel membership at period end Source: https://docs.mag3nt.com/api-reference/membership/cancel-membership-at-period-end /openapi.yaml post /api/membership/cancel Tears down any funded auto-renew agreement and releases its reserve. A soft (no-funds) auto-renew intent is left intact so resume restores it. # Cancel membership auto-renew Source: https://docs.mag3nt.com/api-reference/membership/cancel-membership-auto-renew /openapi.yaml post /api/membership/auto-renew/cancel Cancels the underlying AP2 agreement (funded or wallet-pull) and clears the auto_renew flag. Releases any unused custodial reserve. # Confirm a membership checkout with an on-chain transfer Source: https://docs.mag3nt.com/api-reference/membership/confirm-a-membership-checkout-with-an-on-chain-transfer /openapi.yaml post /api/membership/confirm Verifies the tx on-chain against the checkout amount/asset/network and activates or renews the membership period. Polls briefly for transient confirmation lag; terminal failures (revert, wrong sender/recipient/amount) are never masked. # Enroll in membership auto-renew Source: https://docs.mag3nt.com/api-reference/membership/enroll-in-membership-auto-renew /openapi.yaml post /api/membership/auto-renew mode "wallet": records a wallet-pull authorization backed by a USDC approve you already signed to the treasury operator (allowance must cover at least one period); the cron pulls transferFrom each period. Omitting mode: reserves MAG3NT/USDC into a custodial autopay card when balance covers a renewal, else records a soft (no-funds) intent paid from your signed-in wallet at period end. # Get your membership, tier, usage, plans, and auto-renew state Source: https://docs.mag3nt.com/api-reference/membership/get-your-membership-tier-usage-plans-and-auto-renew-state /openapi.yaml get /api/membership Native Token Rails membership tiers unlock DIRECT (project-token) settlement volume by calendar-month quota. Merchants always receive 100% of payment amounts; membership is an access fee, not a cut. Also returns everything needed to sign a USDC approve for wallet-pull auto-renew. # Start a membership checkout (USDC only) Source: https://docs.mag3nt.com/api-reference/membership/start-a-membership-checkout-usdc-only /openapi.yaml post /api/membership/checkout Creates a pending checkout with a payment amount + treasury address. Confirm with POST /api/membership/confirm once the transfer lands. MAG3NT membership checkout is currently disabled. # Undo a scheduled cancel while still in-period Source: https://docs.mag3nt.com/api-reference/membership/undo-a-scheduled-cancel-while-still-in-period /openapi.yaml post /api/membership/resume # Advance a payment stream by one tick Source: https://docs.mag3nt.com/api-reference/mpp/advance-a-payment-stream-by-one-tick /openapi.yaml post /api/mpp/stream/tick # Close a payment stream Source: https://docs.mag3nt.com/api-reference/mpp/close-a-payment-stream /openapi.yaml post /api/mpp/stream/close # Create an MPP payment session Source: https://docs.mag3nt.com/api-reference/mpp/create-an-mpp-payment-session /openapi.yaml post /api/mpp/session # Discover MPP capabilities for a URL Source: https://docs.mag3nt.com/api-reference/mpp/discover-mpp-capabilities-for-a-url /openapi.yaml get /api/mpp/discover # Get payment stream details Source: https://docs.mag3nt.com/api-reference/mpp/get-payment-stream-details /openapi.yaml get /api/mpp/stream/{id} # Open a payment stream for continuous micropayments Source: https://docs.mag3nt.com/api-reference/mpp/open-a-payment-stream-for-continuous-micropayments /openapi.yaml post /api/mpp/stream/open # (Removed) Make a micropayment via MPP protocol Source: https://docs.mag3nt.com/api-reference/mpp/removed-make-a-micropayment-via-mpp-protocol /openapi.yaml post /api/mpp/pay This proprietary push endpoint has been removed. Use POST /api/pay with { card_id, card_token, url } instead. It automatically decodes the MPP challenge and settles on-chain. # Verify and accept an MPP payment Source: https://docs.mag3nt.com/api-reference/mpp/verify-and-accept-an-mpp-payment /openapi.yaml post /api/mpp/receive # Cancel a pay link Source: https://docs.mag3nt.com/api-reference/pay-links/cancel-a-pay-link /openapi.yaml delete /api/paylinks/{code} # Check pay link payment status Source: https://docs.mag3nt.com/api-reference/pay-links/check-pay-link-payment-status /openapi.yaml get /api/paylinks/{code}/status # Create a shareable payment link Source: https://docs.mag3nt.com/api-reference/pay-links/create-a-shareable-payment-link /openapi.yaml post /api/paylinks # Get public pay link details Source: https://docs.mag3nt.com/api-reference/pay-links/get-public-pay-link-details /openapi.yaml get /api/paylinks/{code} # List pay links for authenticated wallet Source: https://docs.mag3nt.com/api-reference/pay-links/list-pay-links-for-authenticated-wallet /openapi.yaml get /api/paylinks # Prepare payment intent for a pay link Source: https://docs.mag3nt.com/api-reference/pay-links/prepare-payment-intent-for-a-pay-link /openapi.yaml get /api/pay/{code}/prepare Returns everything a payer's wallet or agent needs to build a transaction: intent details, settlement destination, token contract, and settlement_mode. For a DIRECT credential the destination is the merchant's own on-chain holder address instead of the mag3nt treasury; DIRECT also enforces the membership pricing gate and the MAG3NT fee-meter debt floor before returning payment instructions. Agents (JSON Accept header, non-browser user agent) get HTTP 402 with WWW-Authenticate; browsers get HTTP 200. # Resolve a pay link for payment processing Source: https://docs.mag3nt.com/api-reference/pay-links/resolve-a-pay-link-for-payment-processing /openapi.yaml get /api/pay/{code}/resolve Unified resolver used by the universal checkout surface. For a DIRECT credential whose merchant has no active membership plan or has used up their monthly quota, returns the pricing-gate error body instead of link details so a payer is never sent to a merchant who cannot legitimately accept. # Settle a pay link payment Source: https://docs.mag3nt.com/api-reference/pay-links/settle-a-pay-link-payment /openapi.yaml post /api/pay/{code}/settle Universal settlement for both humans and agents. Mode is detected from the body: `tx_hash` (+ optional `protocol`) settles an on-chain wallet or external-protocol payment (verified on-chain before crediting); `protocol` + `payer_card_id` + `payer_card_token` settles an internal platform card-to-card protocol payment. The destination (merchant treasury vs. on-chain holder) and pricing gate follow the same DIRECT/CUSTODIAL rules as prepare; the settled settlement_mode is delivered on the `payment.settled` webhook, not in this response. # Execute a universal outbound payment Source: https://docs.mag3nt.com/api-reference/payments/execute-a-universal-outbound-payment /openapi.yaml post /api/pay Enables any mag3nt card to pay any external x402, MPP, or AP2 endpoint in a single HTTP call. The engine automatically probes the target URL, detects the protocol, and settles on-chain. # Execute a universal outbound payment (alias of /api/pay) Source: https://docs.mag3nt.com/api-reference/payments/execute-a-universal-outbound-payment-alias-of-apipay /openapi.yaml post /api/pay/external Identical handler to POST /api/pay. Prefer this path when disambiguating from the /api/pay/{code}/* pay-link routes. # Check settlement status for a transaction Source: https://docs.mag3nt.com/api-reference/settlement/check-settlement-status-for-a-transaction /openapi.yaml get /api/settlement/status/{txn_id} # Get platform status, supported protocols, and capabilities Source: https://docs.mag3nt.com/api-reference/status/get-platform-status-supported-protocols-and-capabilities /openapi.yaml get /api/status # Get treasury addresses and token registry Source: https://docs.mag3nt.com/api-reference/status/get-treasury-addresses-and-token-registry /openapi.yaml get /api/config # List your registered ERC-20 project tokens Source: https://docs.mag3nt.com/api-reference/tokens/list-your-registered-erc-20-project-tokens /openapi.yaml get /api/tokens # Register an ERC-20 (including B20) for DIRECT credentials Source: https://docs.mag3nt.com/api-reference/tokens/register-an-erc-20-including-b20-for-direct-credentials /openapi.yaml post /api/tokens/register Registers an ERC-20 contract on Base or Base Sepolia for DIRECT credentials (x402/ap2/mpp). Use source byo for your own ERC-20, or source b20 for a B20 token (ERC-20 compatible), including Credential Tokens. Validates the contract on-chain and reads decimals/symbol/name. Idempotent per (owner, network, contract). # Delete a webhook endpoint Source: https://docs.mag3nt.com/api-reference/webhooks/delete-a-webhook-endpoint /openapi.yaml delete /api/webhooks/{id} # Get your webhook delivery log Source: https://docs.mag3nt.com/api-reference/webhooks/get-your-webhook-delivery-log /openapi.yaml get /api/webhooks/deliveries Paginated delivery history across your webhooks. Payload bodies are not included in the list; use has_payload to check replayability. # List registered webhooks Source: https://docs.mag3nt.com/api-reference/webhooks/list-registered-webhooks /openapi.yaml get /api/webhooks Returns all webhooks for the authenticated wallet. Secrets are never returned. # Paymentsettled event delivered to your endpoint Source: https://docs.mag3nt.com/api-reference/webhooks/paymentsettled-event-delivered-to-your-endpoint /openapi.yaml webhook payment.settled Sent when a pay link settles. Verify the `X-mag3nt-Signature` header (`t=,v1=`) using your webhook secret before trusting the payload. Respond 2xx to acknowledge; non-2xx responses are retried with backoff. The `X-mag3nt-Event-Id` header is stable across retries for idempotency. Verify against the RAW request body (the exact bytes received), not a re-serialized object. Use a constant-time comparison and reject events whose timestamp is outside a tolerance window to block replays. TypeScript / Node: ```ts import { createHmac, timingSafeEqual } from "node:crypto"; export function verifyReceipt( secret: string, rawBody: string, signatureHeader: string, toleranceSec = 300, ): boolean { const parts = Object.fromEntries( signatureHeader.split(",").map((kv) => { const i = kv.indexOf("="); return [kv.slice(0, i).trim(), kv.slice(i + 1).trim()]; }), ) as Record; const t = Number(parts.t); const v1 = parts.v1; if (!t || !v1) return false; if (Math.abs(Math.floor(Date.now() / 1000) - t) > toleranceSec) return false; const expected = createHmac("sha256", secret) .update(`${t}.${rawBody}`) .digest("hex"); const a = Buffer.from(expected); const b = Buffer.from(v1); return a.length === b.length && timingSafeEqual(a, b); } ``` Python: ```python import hmac, hashlib, time def verify_receipt( secret: str, raw_body: str, signature_header: str, tolerance_sec: int = 300 ) -> bool: try: parts = dict(p.split("=", 1) for p in signature_header.split(",")) t = int(parts["t"]) v1 = parts["v1"] except (KeyError, ValueError): return False if abs(int(time.time()) - t) > tolerance_sec: return False expected = hmac.new( secret.encode(), f"{t}.{raw_body}".encode(), hashlib.sha256 ).hexdigest() return hmac.compare_digest(expected, v1) ``` # Re-deliver a stored webhook event Source: https://docs.mag3nt.com/api-reference/webhooks/re-deliver-a-stored-webhook-event /openapi.yaml post /api/webhooks/deliveries/{id}/replay Re-POSTs the exact stored envelope (same event id, freshly signed) to the webhook's endpoint. Requires a stored payload - deliveries logged before payload storage was added cannot be replayed. # Register a webhook endpoint Source: https://docs.mag3nt.com/api-reference/webhooks/register-a-webhook-endpoint /openapi.yaml post /api/webhooks Register an HTTPS endpoint to receive signed `payment.settled` events when your pay links settle. The signing secret is returned ONCE in this response and cannot be retrieved again. Use it to verify the X-mag3nt-Signature header on each delivery. Max 5 active webhooks per wallet. URLs must be https and may not target private/loopback hosts. # Rotate a webhook's signing secret Source: https://docs.mag3nt.com/api-reference/webhooks/rotate-a-webhooks-signing-secret /openapi.yaml post /api/webhooks/{id}/rotate The new secret is returned ONCE and cannot be retrieved again. The prior secret stops verifying immediately. # Send a signed test payment.settled event Source: https://docs.mag3nt.com/api-reference/webhooks/send-a-signed-test-paymentsettled-event /openapi.yaml post /api/webhooks/{id}/test Delivers a signed test event (event id prefixed `evt_test_`, `data.test: true`) to the webhook's endpoint so you can verify your handler end-to-end before real money moves. # List withdrawal history Source: https://docs.mag3nt.com/api-reference/withdrawals/list-withdrawal-history /openapi.yaml get /api/withdrawals Returns up to 50 most recent withdrawals for the authenticated wallet. # Withdraw unspent funds back to your wallet Source: https://docs.mag3nt.com/api-reference/withdrawals/withdraw-unspent-funds-back-to-your-wallet /openapi.yaml post /api/withdraw Initiates a withdrawal of USDC from your treasury balance to an on-chain wallet address. A flat network fee is deducted from the requested amount. The net amount is sent on-chain via CDP; the fee is retained as platform revenue. Withdrawals are processed asynchronously: check status via GET /api/withdrawals. # Discover x402 payment requirements for a URL Source: https://docs.mag3nt.com/api-reference/x402/discover-x402-payment-requirements-for-a-url /openapi.yaml get /api/x402/discover # (Removed) Pay for a service via x402 protocol Source: https://docs.mag3nt.com/api-reference/x402/removed-pay-for-a-service-via-x402-protocol /openapi.yaml post /api/x402/pay This proprietary push endpoint has been removed. Use POST /api/pay with { card_id, card_token, url } instead. It automatically detects x402 and settles on-chain. # Verify and accept an x402 payment Source: https://docs.mag3nt.com/api-reference/x402/verify-and-accept-an-x402-payment /openapi.yaml post /api/x402/receive # Authentication Source: https://docs.mag3nt.com/authentication How to authenticate with the mag3nt API using API keys. ## API Keys All API requests are authenticated with an API key. Generate one from the [mag3nt dashboard](https://mag3nt.com), then include it in every request: ```http theme={null} Authorization: Bearer mag3nt_live_your_api_key_here ``` ## Using with the SDK ```typescript TypeScript theme={null} import { Mag3nt } from "@mag3nt/sdk"; const mag3nt = new Mag3nt({ serverURL: "https://mag3nt.com", security: { bearerAuth: process.env.MAG3NT_API_KEY, }, }); ``` ```python Python theme={null} import mag3nt from mag3nt.models.components import Security import os sdk = mag3nt.Mag3nt( server_url="https://mag3nt.com", security=Security(bearer_auth=os.environ["MAG3NT_API_KEY"]), ) ``` ## Managing keys ```typescript theme={null} // Generate a new key const key = await mag3nt.keys.keysCreate(); console.log(key.apiKey); // ⚠️ Store securely:shown only once // List active keys const keys = await mag3nt.keys.keysList(); // Revoke a compromised key await mag3nt.keys.keysRevoke(keyHash); // Validate a key is working const check = await mag3nt.keys.keysValidate(); console.log(check.valid); // true ``` ## Best practices **Never expose API keys in client-side code.** API keys grant full access to your treasury. Use them only in server-side code or secure agent environments. * **Use environment variables**:never hardcode keys in source * **One key per agent**:if an agent is compromised, revoke only its key * **Rotate regularly**:generate new keys and revoke old ones ## Public endpoints These endpoints require no authentication: | Endpoint | Description | | ------------------- | ------------------------------------ | | `statusGet` | Platform health | | `statusGetConfig` | Treasury addresses and configuration | | `fundingListTokens` | Supported tokens per network | | `payLinksGet` | Public pay link details | | `payLinksResolve` | Resolve pay link for payment | | `payLinksPrepare` | Prepare payment for a pay link | | `payLinksSettle` | Submit on-chain payment proof | # Cards Source: https://docs.mag3nt.com/concepts/cards Virtual payment cards for AI agents:issuance, controls, and lifecycle. ## Overview Cards are the core primitive. Each card is a virtual payment instrument backed by your USDC or pathUSD treasury balance. Agents use cards to pay for APIs, services, and resources. ## Card lifecycle ```mermaid theme={null} stateDiagram-v2 [*] --> ACTIVE: Funded from balance [*] --> PENDING_FUNDING: Pay-and-issue (tx_hash) PENDING_FUNDING --> ACTIVE: On-chain confirmed PENDING_FUNDING --> FUNDING_FAILED: Timeout (30min) ACTIVE --> FROZEN: cardsFreeze FROZEN --> ACTIVE: cardsUnfreeze ACTIVE --> USED: Single-use card spent ACTIVE --> EXPIRED: TTL elapsed ACTIVE --> CLOSED: cardsClose FROZEN --> CLOSED: cardsClose EXPIRED --> CLOSED: cardsClose USED --> CLOSED: cardsClose ``` `CLOSED` is a terminal, one-way state. A closed card stops working immediately and leaves the wallet view, but its records are never deleted: full history stays available through the account activity feed. ## Issue a card ```typescript TypeScript theme={null} const card = await mag3nt.cards.cardsCreate({ purpose: "Research Agent", limitAmount: 50, // Max spend (USDC/pathUSD) network: "eip155:8453", // Base asset: "USDC", singleUse: false, // Reusable expiresIn: 24, // Hours (0 = never) }); ``` ```python Python theme={null} card = sdk.cards.cards_create( purpose="Research Agent", limit_amount=50, network="eip155:8453", asset="USDC", single_use=False, expires_in=24, ) ``` ## Bulk issuance Create up to 1,000 cards atomically: ```typescript theme={null} const batch = await mag3nt.cards.cardsBulkCreate({ cards: [ { purpose: "Agent Alpha", limitAmount: 25 }, { purpose: "Agent Beta", limitAmount: 25 }, { purpose: "Agent Gamma", limitAmount: 50 }, ], network: "eip155:8453", asset: "USDC", }); // All-or-nothing: if total exceeds balance, none are created ``` ## Spending controls ### MCC locks Restrict which merchant categories a card can pay: ```typescript theme={null} await mag3nt.cards.cardsUpdateControls(cardId, { mccLocks: "5411,5812", // Only grocery and restaurants }); ``` ### Freeze / unfreeze Instantly block all transactions on a compromised card: ```typescript theme={null} await mag3nt.cards.cardsFreeze(cardId); // Card is immediately blocked:no payments can process await mag3nt.cards.cardsUnfreeze(cardId); // Card is restored to ACTIVE ``` ## Move funds back to treasury Sweep a card's unspent balance back into your treasury, where it can be withdrawn off-platform. For `EXPIRED` cards this always performs a full sweep. For `ACTIVE` or `FROZEN` cards, omit the amount to sweep everything, or pass an amount for a partial claim (the card stays active with the remainder). Pending charges and mandate holds are excluded from the sweepable balance, so a claim can never strand an in-flight payment. ```typescript theme={null} // Full sweep await mag3nt.cards.cardsClaim(cardId); // Partial claim: pull $5 back, leave the rest on the card await mag3nt.cards.cardsClaim(cardId, { amount: 5 }); ``` ## Close a card Retire a card you no longer need. Closing is a one-way action allowed only when the card is empty and has no open obligations: * Remaining balance is zero (sweep with a claim first if needed) * No in-flight pending transaction * No open payment stream * No active, unexpired AP2 mandate ```typescript theme={null} await mag3nt.cards.cardsClose(cardId); ``` A closed card disappears from the wallet view. Its history is preserved and remains accessible from the account activity feed. ## Audit trail Every transaction is recorded with full metadata. Read a single card's history, or the whole wallet's activity across every card (including closed ones): ```typescript theme={null} // One card const txns = await mag3nt.cards.cardsListTransactions(cardId); for (const txn of txns.transactions) { console.log(`${txn.amount} USDC/pathUSD to ${txn.merchant} via ${txn.protocol}`); } // All cards, including closed: each row is tagged with card_purpose and card_status const all = await mag3nt.transactions.list(); ``` ## Sandbox & testnet mag3nt uses **network-based** environment isolation:no separate test API keys needed. Issue a card on a testnet network to activate sandbox mode: ```typescript TypeScript theme={null} const testCard = await mag3nt.cards.cardsCreate({ purpose: "Testing Agent", limitAmount: 100, network: "eip155:84532", // Base Sepolia = sandbox asset: "USDC", }); ``` ```python Python theme={null} test_card = sdk.cards.cards_create( purpose="Testing Agent", limit_amount=100, network="eip155:84532", # Base Sepolia = sandbox asset="USDC", ) ``` ### How it works \| `eip155:8453` (Base) | `production` | Real USDC | \| `solana:mainnet` (Solana) | `production` | Real USDC | \| `eip155:4217` (Tempo) | `production` | Real USDC or pathUSD | \| `eip155:84532` (Base Sepolia) | `sandbox` | Test USDC:no real value | Every payment response includes an `environment` field: ```json theme={null} { "success": true, "environment": "sandbox" } ``` Sandbox transactions deduct from your card balance just like production, but use test tokens with no real value. Use sandbox to validate your integration before going live. ### Same API key, same endpoints Your API key works for both environments. The card's network is the boundary:not the key, not the endpoint. A single account can have both mainnet and testnet cards simultaneously. # Credential Tokens (CT) Source: https://docs.mag3nt.com/concepts/credential-tokens Fixed-supply B20 tokens for a credential, Uniswap V4 public markets on Base, and Sablier vesting for the kept slice. A **Credential Token (CT)** is a fixed-supply B20 token (ERC-20 compatible) tied to one credential. Mag3nt prepares deploy and market calldata; you sign every money move from your own wallet. Mag3nt does not custody LP or sweep trading fees. API path segments still use `crt` for compatibility. Product language is **Credential Token (CT)**. ## Launch | Method | Path | Purpose | | ------ | ---------------------------- | -------------------------------------------------------- | | `GET` | `/api/cards/{id}/crt` | Status, launch fee, holder balance, sendability | | `POST` | `/api/cards/{id}/launch-crt` | Create and deploy the CT (charges the MAG3NT launch fee) | The full supply mints to your account. Launch fee is paid in \$MAG3NT from your wallet (approve then server pull). A credential that has already been transferred on the marketplace cannot launch a CT. After launch, register the CT as a project token (`source: b20`) if you want DIRECT credentials to accept it. ## Public market (Uniswap V4) | Method | Path | Purpose | | ------ | -------------------------------------------- | -------------------------------------------------- | | `POST` | `/api/cards/{id}/crt-market/prepare` | Prepare list / approve / optional vesting calldata | | `POST` | `/api/cards/{id}/crt-market/confirm` | Confirm the listing transaction | | `POST` | `/api/cards/{id}/crt-market/vesting-confirm` | Confirm the Sablier lock for any kept slice | | `GET` | `/api/cards/{id}/crt-market` | Market details, pool, vesting links | | `GET` | `/api/crt-markets` | Public listed markets | Markets run on **Base mainnet** in production and on staging when `B20_NETWORK=base`. Explorer links use basescan.org in that configuration. You may keep up to **25%** of supply in a Sablier vesting stream. The rest seeds the Uniswap V4 market. Send-to-wallet only applies to amounts **released** from vesting, not the locked slice. ## Holdings | Method | Path | Purpose | | ------ | --------------- | -------------------------------------------------- | | `GET` | `/api/holdings` | CT balances across deployed tokens for your wallet | ## Related * [Project tokens](/concepts/project-tokens) * [Marketplace](/concepts/marketplace) * [Membership](/concepts/membership) # DIRECT fee meter Source: https://docs.mag3nt.com/concepts/fee-meter Prepaid MAG3NT balance that covers per-settle fees when you exceed membership quota. Every settled DIRECT payment above your membership quota debits a flat fee in **\$MAG3NT**. The fee meter is a prepaid balance on your account. If the meter is empty while you are over quota, discovery and accept for DIRECT credentials are withheld until you deposit. Merchants still receive 100% of the payment amount. The meter only covers Mag3nt's access fee for overage volume. ## API surface | Method | Path | Purpose | | ------ | ------------------- | ---------------------------------------------------------- | | `GET` | `/api/fees/balance` | Current prepaid MAG3NT balance and recent fee events | | `POST` | `/api/fees/deposit` | Credit the meter after a verified on-chain MAG3NT transfer | ## Related * [Membership](/concepts/membership) * [Project tokens](/concepts/project-tokens) * [\$MAG3NT token](/concepts/token) # Funding Source: https://docs.mag3nt.com/concepts/funding Deposits, treasury balance, and multi-network support. ## How funding works 1. **Deposit** USDC to your treasury address on any supported EVM network or Solana, or pathUSD/USDC on Tempo. 2. **System detects** the deposit automatically (no API call needed) 3. **Balance updates**:your treasury balance reflects the deposit 4. **Issue cards** backed by your available balance ## Check your treasury address ```typescript theme={null} const config = await mag3nt.status.statusGetConfig(); console.log("EVM treasury:", config.treasury?.evm); console.log("Solana treasury:", config.treasury?.solana); ``` ## Supported tokens ```typescript theme={null} const tokens = await mag3nt.funding.fundingListTokens(); // Returns supported tokens per network: // eip155:8453 → USDC (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913) // solana:mainnet → USDC (EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v) // eip155:4217 → pathUSD (0x20c0000000000000000000000000000000000000), USDC (0x20c000000000000000000000b9537d11c60e8b50) ``` ## Check balance ```typescript theme={null} const balance = await mag3nt.funding.fundingGetBalance(); // Returns: // - total_funded: Total USDC/pathUSD deposited // - total_allocated: Amount locked in active cards // - total_spent: Amount spent through transactions // - available: Spendable balance ``` ## Supported Settlement Networks | Network | Chain ID | Asset | Contract Address | | ------- | -------------- | ------- | ---------------------------------------------- | | Base | eip155:8453 | USDC | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` | | Solana | solana:mainnet | USDC | `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` | | Tempo | eip155:4217 | pathUSD | `0x20c0000000000000000000000000000000000000` | | Tempo | eip155:4217 | USDC | `0x20c000000000000000000000b9537d11c60e8b50` | ## Supported USDC Account Networks (Funding) You can fund your treasury by depositing USDC on the following networks: * **EVMs**: Optimism, Arbitrum, Polygon, Avalanche, Ethereum, Base, Base Sepolia * **Solana**: Mainnet # Credential business transfer Source: https://docs.mag3nt.com/concepts/marketplace List and transfer a credential business (proof of record) against USDC on the Mag3nt marketplace. The marketplace is for **transferring a credential business**, not for trading identity as a collectible. When a listing settles, Mag3nt re-keys the on-platform record (ownership, pay links, history) to the buyer against USDC. Off-platform assets and how you hand over the underlying business stay between the parties. Sellers can document transfer context in their listing materials. ## What buyers get * The credential and its Mag3nt record * Associated pay links and payment history on Mag3nt * Proof of business transfer on the marketplace record ## What buyers do not automatically get * Off-platform accounts, domains, or private keys outside Mag3nt * A guarantee of the underlying off-platform business unless you arrange that separately ## API surface | Method | Path | Purpose | | ------ | --------------------------- | --------------------------------- | | `POST` | `/api/cards/{id}/list` | List a credential for sale (USDC) | | `GET` | `/api/listings` | Browse open listings | | `GET` | `/api/listings/{id}` | Listing detail | | `GET` | `/api/cards/{id}/listing` | Listing for a specific credential | | `POST` | `/api/listings/{id}/buy` | Buy and settle the transfer | | `POST` | `/api/listings/{id}/cancel` | Seller cancel while still listed | Once a listing is **SOLD**, launching a Credential Token for that credential is closed. Tokenizing after a settled transfer would re-monetize the record out from under the sale. ## Related * [Credential Tokens](/concepts/credential-tokens) * [Cards](/concepts/cards) # Membership and Native Token Rails Source: https://docs.mag3nt.com/concepts/membership Token utility plans that unlock DIRECT settlement quotas for ERC-20 project tokens. Membership unlocks **DIRECT** settlement: accept payments into your own on-chain holder, denominated in a registered **project token** (an ERC-20, including B20 tokens). It is an access fee for volume, not a cut of payments. Merchants still receive 100% of each payment amount. ## Plans | Tier | Role | | -------------- | ------------------------------------------------ | | **Starter** | Entry quota of DIRECT settles per calendar month | | **Growth** | Higher monthly quota | | **Enterprise** | Unlimited / custom (contact sales) | Pricing is billed in **USDC on Base**. Checkout creates a pending invoice; you confirm with an on-chain transfer to the treasury. ## API surface | Method | Path | Purpose | | ------ | ----------------------------------- | ---------------------------------------------------------- | | `GET` | `/api/membership` | Current plan, tier, usage, plans catalog, auto-renew state | | `POST` | `/api/membership/checkout` | Start USDC checkout | | `POST` | `/api/membership/confirm` | Confirm payment with `checkout_id` + `tx_hash` | | `POST` | `/api/membership/cancel` | Cancel at period end | | `POST` | `/api/membership/resume` | Undo a scheduled cancel while still in period | | `POST` | `/api/membership/auto-renew` | Enroll wallet-pull or funded auto-renew | | `POST` | `/api/membership/auto-renew/cancel` | Turn auto-renew off | ## Auto-renew Preferred path is **wallet-pull**: you approve USDC to the operator once; Mag3nt pulls each period via AP2. `GET /api/membership` includes `wallet_autorenew` with operator address, price, and suggested allowance. If quota is exhausted or the plan is expired, DIRECT accept paths return unavailable (HTTP 402). That is intentional: pricing gates access. ## Related * [Project tokens](/concepts/project-tokens) * [Fee meter](/concepts/fee-meter) * [Settlement](/concepts/settlement) # Project tokens (ERC-20) Source: https://docs.mag3nt.com/concepts/project-tokens Register an ERC-20 (including B20) so DIRECT credentials can accept that asset on Native Token Rails. A **project token** is an ERC-20 contract you register with Mag3nt so a DIRECT credential can accept x402 / AP2 / MPP payments in that asset. B20 tokens are ERC-20 compatible. You register them the same way (`source: b20`), including Credential Tokens (CT) you launched on Mag3nt. Bring-your-own ERC-20s use `source: byo`. The dashboard panel for this is labeled **Native Tokens**. The API and database use the name project tokens. Both refer to this registry. Do not confuse this with chain-native gas assets (ETH, SOL). Those are not registered here and are not used as DIRECT funding assets. ## API surface | Method | Path | Purpose | | ------ | ---------------------- | ---------------------------------------------------------------------- | | `POST` | `/api/tokens/register` | Register a contract on Base or Base Sepolia (`source`: `byo` or `b20`) | | `GET` | `/api/tokens` | List tokens you have registered | Registration does not mint supply. It only tells Mag3nt which ERC-20 can back DIRECT credentials and pay links for your account. When issuing a credential with `settlement_mode: DIRECT`, use a registered token (or USDC) as the funding asset so prepare and settle resolve the correct on-chain destination. ## Related * [Membership](/concepts/membership) for DIRECT quotas * [Credential Tokens](/concepts/credential-tokens) if the asset is a Mag3nt-launched CT * [Fee meter](/concepts/fee-meter) for prepaid MAG3NT overage fees # Settlement Source: https://docs.mag3nt.com/concepts/settlement How payments settle on-chain: custodial batch settlement and DIRECT (non-custodial) project-token rails. ## Settlement modes | Mode | What happens | | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **CUSTODIAL** | Payment credits a platform ledger balance, then settles on-chain in batch (USDC / pathUSD). | | **DIRECT** | Payment lands on-chain at the merchant's own holder address in a registered project token (ERC-20, including B20). Requires an active Native Token Rails membership. | Set `settlement_mode` at credential issuance (`POST /api/issue`). It cannot be changed after creation. `GET /api/pay/{code}/prepare` and settle responses include `settlement_mode` so payers and agents know which path applies. ## How custodial settlement works When an agent makes a custodial payment, settlement is automatic: 1. **Payment authorized**: deducted from the card's balance instantly 2. **Queued for settlement**: the transaction enters the settlement pipeline 3. **Settled on-chain**: USDC or pathUSD is transferred to the merchant 4. **Confirmed**: the transaction status is updated with the on-chain hash ## Fees | Component | Amount | | ------------------- | ---------------------- | | Platform fee | 0.5% of transaction | | Per-transaction fee | \$0.001 (USDC/pathUSD) | | On-chain gas | Covered by mag3nt | **Example:** A 10.00 token payment (USDC/pathUSD) costs 0.051 tokens: merchant receives 9.949 tokens. ## Check settlement status ```typescript theme={null} const status = await mag3nt.settlement.settlementGetStatus(transactionId); console.log(status.settlement.status); // PENDING | IN_PROGRESS | SETTLED | FAILED console.log(status.settlement.feeAmount); // 0.051 console.log(status.settlement.settledAt); // 2026-05-21T00:30:00Z ``` ## Settlement states | Status | Description | | ------------- | ------------------------------------------------- | | `SANDBOX` | Testnet payment authorized. Not settled on-chain. | | `PENDING` | Payment authorized, awaiting batch settlement | | `IN_PROGRESS` | Settlement queued and actively being processed | | `SETTLED` | On-chain transfer confirmed | | `FAILED` | Settlement failed:funds returned to card | ## Timing * **Authorization**: Instant * **Instant Settlement**: Triggers immediately for network-fee efficient transactions. * **Batch Settlement**: Transactions that are not currently fee-efficient are grouped and settled rapidly in batches to optimize network costs. * **On-chain confirmation**: A few seconds on Base, Solana, and Tempo. Custodial settlement runs automatically. You do not need to trigger it: check status when you need confirmation. ## DIRECT settlement DIRECT credentials do not use the custodial ledger for receives. Value is the on-chain balance of the funding asset at `holder_address`. * Membership quota meters DIRECT settles per calendar month ([Membership](/concepts/membership)). * Over-quota settles debit the prepaid MAG3NT fee meter ([Fee meter](/concepts/fee-meter)). * Register the ERC-20 first ([Project tokens](/concepts/project-tokens)). If the plan is expired or quota is exhausted (and the fee meter cannot cover overage), DIRECT prepare/discover returns unavailable. # $MAG3NT - Token Utility Source: https://docs.mag3nt.com/concepts/token Why $MAG3NT exists, how you earn on mag3nt., and what Pro / Yield+ credentials unlock. **Token**: `$MAG3NT` | **Chain**: Base | **Contract**: `0xF4EaF78b484ECe2a9b495eb02C9Dcfa0F8920631` **Ticker:** \$MAG3NT\ **Standard:** ERC-20 on Base (`eip155:8453`) This document explains why `$MAG3NT` exists and how it captures the value of the mag3nt. network. No jargon, no hype - just the economic engine of a stablecoin-native payment network. *** ## The Vision: A Global Settlement Layer mag3nt. is a payment and settlement network built for the agentic economy and global commerce. We move money using stablecoins, making transactions instant, borderless, and programmable. * **Pay** - Use a mag3nt. credential to pay any merchant or agent endpoint. * **Receive** - Spin up a **paylink** to accept payments instantly without a wallet address exchange. * **Request** - Use paylinks as invoices or simple payment requests in any chat. * **Settle** - Move value across borders. With integrated on-ramps and off-ramps, mag3nt. handles the entire settlement lifecycle from local currency to stablecoin and back. *** ## How You Make Money on mag3nt. mag3nt. is not only a way to spend - it is a way to earn: * **Earn yield** on the stablecoins sitting idle in your credentials, automatically, while they stay ready to spend. * **Get paid** through paylinks - sell a service, an API, or a product and collect from anyone, anywhere, instantly. * **Charge your own users** - issue sub-credentials and bill per use, so developers and businesses can run paid services on top of mag3nt. * **Settle across borders** without losing money to slow, expensive rails. Holding `$MAG3NT` improves all of it: higher yield, lower fees, and access to the Pro / Yield+ tools that turn a credential into a business. *** ## Why the Token Matters mag3nt. keeps the basics simple and cheap: creating a credential and claiming a basic paylink stays free. `$MAG3NT` is for users who want better economics and more powerful credentials. As the network grows, more value moves through mag3nt. credentials and paylinks. The token makes that value useful inside the product: * higher yield on idle credential balances, * access to Pro / Yield+ credential features, * discounted premium services when paid in `$MAG3NT`, * and governance over the parts of the network users care about: fees, yield partners, and settlement corridors. ## Pro / Yield+ Credentials The **Pro / Yield+** credential is the premium version of a mag3nt. credential. It is built for people, agents, merchants, and teams that move money often and need more than a simple payment card. ### 1. Boosted Auto-Yield Idle stablecoin balances can earn yield through integrated non-custodial yield APIs. Pro / Yield+ users receive a higher yield rate, and `$MAG3NT` stakers receive the best available boost. Your money can keep working while it waits to be spent, requested, or settled. ### 2. Programmable Sub-Credentials Issue scoped "child" credentials to sub-agents, employees, or customers. * **Granular Limits**: Set specific spending caps for each sub-credential. * **Instant Revocation**: Kill any sub-credential at any time without affecting your main account. * **Auto-Reload**: Automatically top up sub-credentials from a parent credential when they run low. ### 3. Advanced Spend Policies Control exactly how money moves with programmable rules: * **Merchant Allowlists**: Restrict spending to specific verified merchants. * **Velocity Caps**: Limit how much can be spent per hour, day, or transaction. * **Time Windows**: Allow spending only during specific hours. ### 4. Paylink Business Tools Turn a paylink into a serious payment request or settlement page: * **Verified Paylinks**: Show users that the receiver is verified. * **Branded Checkout**: A cleaner payment page for your business, agent, or service. * **Receipts & Statements**: Cleaner records for customers, merchants, and accounting. * **Webhook Notifications**: Get notified instantly when a payment lands. ### 5. Priority Settlement Pro / Yield+ users get faster settlement handling, higher limits, and better support for high-volume payment flows. This matters when paylinks are used for commerce, invoices, remittance, or recurring agent activity. ### 6. Team & Agent Controls Manage multiple agents, teammates, or customers across your credentials: * **Roles and Permissions**: Decide who can issue, fund, freeze, or redeem credentials. * **Audit Logs**: See exactly who moved money and when. * **Instant Freeze**: Stop a credential immediately if something looks wrong. ### 7. Flexible Access You can access Pro / Yield+ in three ways: * stake enough `$MAG3NT` and unlock it, * pay monthly in `$MAG3NT` at a discount, * or pay monthly in USDC at the standard price. This keeps mag3nt. open to everyone while giving token holders better economics. *** ## \$MAG3NT Token Utility The token is the key to unlocking the best economics on the network. * **Fee Discounts**: Staking `$MAG3NT` reduces your transaction fees even further. For high-volume merchants, this creates a massive economic incentive to hold and lock the token. * **Yield Boosts**: The more `$MAG3NT` you stake, the higher the APY you receive on your idle credential balances. * **Unlock Pro for Free**: Instead of a monthly subscription, users can stake a specific amount of `$MAG3NT` to unlock all Pro / Yield+ features for free. * **Discounted Premium Payments**: Users who do not want to stake can still pay for Pro / Yield+ in `$MAG3NT` at a discount, or pay the full price in USDC. * **Protocol Buybacks**: When enabled by governance, a portion of protocol revenue can be used to buy back `$MAG3NT` on the open market. * **Governance**: Holders help decide protocol parameters, including fee levels, yield partner integrations, and new settlement corridors. `$MAG3NT` is the value-capture layer of a network that settles real money. As mag3nt. expands from agent payments to global cross-border settlement, the token ensures that the value created by the network stays within the ecosystem. # Agent Integrations (MCP) Source: https://docs.mag3nt.com/guides/agent-integration Give your AI agents a wallet by connecting them to the mag3nt MCP server. ## Overview The Model Context Protocol (MCP) is an open standard that lets AI agents use external tools and APIs. The hosted mag3nt MCP server turns the full mag3nt API into agent-native tools, so an assistant can issue cards, check balances, pay endpoints, and reconcile activity on its own. The server is live at [mcp.mag3nt.com](https://mcp.mag3nt.com). That page also offers one-click install links for popular clients. Connection URL: `https://mcp.mag3nt.com/mcp` (modern Streamable HTTP transport). Authenticate with the header `api-key-auth: `. Generate a key from the Developer tab at [mag3nt.com](https://mag3nt.com). Do not use the legacy `https://mcp.mag3nt.com/sse` endpoint. The HTTP+SSE transport is deprecated. Always use the `/mcp` Streamable HTTP endpoint. ## Install Replace `mag3nt_live_YOUR_API_KEY` with your own key in each example. ### Cursor Open the [mcp.mag3nt.com](https://mcp.mag3nt.com) install page and click Cursor for one-click setup, or add it manually under Cursor Settings > MCP: ```json theme={null} { "mcpServers": { "Mag3nt": { "command": "npx", "args": [ "-y", "mcp-remote@0.1.25", "https://mcp.mag3nt.com/mcp", "--header", "api-key-auth:${API_KEY_AUTH}" ], "env": { "API_KEY_AUTH": "mag3nt_live_YOUR_API_KEY" } } } } ``` ### Claude Code ```bash theme={null} claude mcp add --transport http Mag3nt https://mcp.mag3nt.com/mcp --header "api-key-auth:mag3nt_live_YOUR_API_KEY" ``` ### Claude Desktop Open Settings > Developer > Edit Config, then merge this into the `mcpServers` object in `claude_desktop_config.json` and restart Claude Desktop: ```json theme={null} { "mcpServers": { "Mag3nt": { "command": "npx", "args": [ "-y", "mcp-remote@0.1.25", "https://mcp.mag3nt.com/mcp", "--header", "api-key-auth:${API_KEY_AUTH}" ], "env": { "API_KEY_AUTH": "mag3nt_live_YOUR_API_KEY" } } } } ``` ### VS Code Use the install link on [mcp.mag3nt.com](https://mcp.mag3nt.com), or add the same `Mag3nt` server entry shown above to your VS Code MCP configuration. ### Gemini CLI ```bash theme={null} gemini mcp add --transport http Mag3nt https://mcp.mag3nt.com/mcp --header "api-key-auth:mag3nt_live_YOUR_API_KEY" ``` ### Codex CLI Add this to your Codex config: ```toml theme={null} [mcp_servers.Mag3nt] url = "https://mcp.mag3nt.com/mcp" http_headers = { "api-key-auth" = "mag3nt_live_YOUR_API_KEY" } ``` ## Available tools Once connected, your agent can call every capability of the mag3nt API. Tools are grouped by area below. ### Cards | Tool | What it does | | ------------------------------- | -------------------------------------------------------------------- | | `cards-cards-create` | Issue a virtual card backed by treasury balance | | `cards-cards-bulk-create` | Issue up to 1,000 cards in one atomic request | | `cards-cards-list` | List all cards for the wallet | | `cards-cards-list-transactions` | A single card's transaction history | | `cards-cards-top-up` | Add funds to an active card from treasury | | `cards-cards-freeze` | Block all spending on a card | | `cards-cards-unfreeze` | Resume spending on a frozen card | | `cards-cards-claim` | Move a card's unspent funds back to treasury (full or partial sweep) | | `cards-cards-close` | Retire an empty card with no open obligations | | `cards-cards-update-controls` | Update MCC locks and single-use settings | | `transactions-list-account` | Wallet activity across every card, including closed ones | ### Payments | Tool | What it does | | --------------------------- | ---------------------------------------------------------------------------------------------- | | `payments-payments-execute` | Pay any x402, AP2, or MPP endpoint with a card; auto-detects the protocol and settles on-chain | ### Funding and withdrawals | Tool | What it does | | ------------------------------------ | ---------------------------------------------------- | | `funding-funding-get-balance` | Treasury balance for the wallet | | `funding-funding-list-tokens` | Accepted tokens per network | | `funding-funding-verify` | Credit treasury from an on-chain funding transaction | | `funding-funding-get-wallet-balance` | Real-time on-chain balance for any address | | `withdrawals-withdrawals-create` | Withdraw treasury funds to a wallet | | `withdrawals-withdrawals-list` | Withdrawal history | ### Pay links | Tool | What it does | | -------------------------------- | -------------------------------- | | `pay-links-pay-links-create` | Create a shareable payment link | | `pay-links-pay-links-list` | List your pay links | | `pay-links-pay-links-get` | Get public pay link details | | `pay-links-pay-links-cancel` | Cancel a pay link | | `pay-links-pay-links-get-status` | Check payment status | | `pay-links-pay-links-resolve` | Resolve a link for processing | | `pay-links-pay-links-prepare` | Discover payment requirements | | `pay-links-pay-links-settle` | Submit on-chain settlement proof | ### Protocols | Tool | What it does | | ------------------------------ | -------------------------------------------------- | | `x402-x402-discover` | Discover x402 payment requirements for a URL | | `x402-x402-receive` | Verify and accept an x402 payment | | `ap2-ap2-get-agent-card` | Get the default agent card for AP2 | | `ap2-ap2-list-payment-methods` | List AP2 payment methods | | `ap2-ap2-create-mandate` | Create a spending mandate for recurring payments | | `ap2-ap2-execute` | Execute a payment against a mandate | | `ap2-ap2-list-mandates` | List a card's mandates | | `ap2-ap2-settle` | Settle an AP2 payment between agents | | `mpp-mpp-create-session` | Create an MPP payment session | | `mpp-mpp-discover` | Discover MPP capabilities for a URL | | `mpp-mpp-receive` | Verify and accept an MPP payment | | `mpp-mpp-streams-open` | Open a payment stream for continuous micropayments | | `mpp-mpp-streams-tick` | Advance a payment stream by one tick | | `mpp-mpp-streams-close` | Close a payment stream | | `mpp-mpp-streams-get` | Get payment stream details | ### Keys, webhooks, and status | Tool | What it does | | ----------------------------------- | ---------------------------------------------- | | `keys-keys-create` | Generate an API key (returned once) | | `keys-keys-list` | List API keys | | `keys-keys-revoke` | Revoke an API key | | `keys-keys-validate` | Validate an API key | | `webhooks-webhooks-create` | Register a signed `payment.settled` webhook | | `webhooks-webhooks-list` | List registered webhooks | | `webhooks-webhooks-delete` | Delete a webhook | | `webhooks-webhooks-rotate` | Rotate the webhook signing secret (shown once) | | `webhooks-webhooks-test` | Send a signed test `payment.settled` delivery | | `webhooks-webhooks-list-deliveries` | Paginated delivery log | | `webhooks-webhooks-replay-delivery` | Re-POST a stored delivery envelope | | `settlement-settlement-get-status` | Check settlement status for a transaction | | `status-status-get` | Platform status, protocols, and capabilities | | `status-status-get-config` | Treasury addresses and token registry | ### Membership, tokens, marketplace, and CT markets After Speakeasy regenerates MCP from the updated OpenAPI, these areas are also exposed as tools (names follow Speakeasy tagging). Until regeneration lands, call them via the REST API: | Area | Paths | | ------------------ | ---------------------------------------------------------------- | | Membership | `/api/membership`, checkout, confirm, cancel, resume, auto-renew | | Project tokens | `/api/tokens/register`, `/api/tokens` | | Fee meter | `/api/fees/balance`, `/api/fees/deposit` | | Billing agreements | `/api/billing/agreements` | | Marketplace | `/api/cards/{id}/list`, `/api/listings`, buy/cancel | | Credential Tokens | `/api/cards/{id}/crt`, launch-crt, crt-market prepare/confirm | | Holdings | `/api/holdings` | ## Try it Once connected, ask your agent something like: > Issue a card for \$10, use it to pay for data from weather-api.com, then move any unspent funds back to my treasury and close the card. The agent will call `cards-cards-create`, `payments-payments-execute`, `cards-cards-claim`, and `cards-cards-close` in sequence, with the full record available through `transactions-list-account`. # mag3nt. Source: https://docs.mag3nt.com/index Payment infrastructure for AI agents. Issue virtual cards, pay for APIs, settle in USDC & pathUSD. ## What is mag3nt.? mag3nt. gives AI agents the ability to **spend and earn money** autonomously. Issue virtual payment cards, pay for API access via open protocols (x402, AP2, MPP), and settle in USDC or pathUSD across Base, Solana, and Tempo. Issue your first card in 5 minutes Full OpenAPI reference: cards, protocols, membership, project tokens, CT markets, marketplace, webhooks npm install @mag3nt/sdk Give your MCP agents a wallet ## How it works Send USDC or pathUSD to your treasury address on Base, Solana, or Tempo. Your balance is available instantly. Create virtual payment cards backed by your treasury balance. Each card has its own spending limit, controls, and purpose. Your agents use cards to pay for APIs via x402, AP2, or MPP protocols. Every transaction is tracked and auditable. Payments settle on-chain in USDC or pathUSD automatically. 0.05% + \$0.001 per transaction. ## Supported protocols | Protocol | Direction | Use case | | -------- | ------------- | --------------------------------------------------------- | | **x402** | Bidirectional | HTTP 402 payment-required flows:agent pays for API access | | **AP2** | Bidirectional | Agent-to-agent payments with spending mandates | | **MPP** | Bidirectional | Micropayment streaming:pay-per-token, pay-per-call | ## Supported Settlement Networks Base, Solana, and Tempo, settling in USDC (and pathUSD on Tempo). ## Supported USDC Account Networks Optimism, Arbitrum, Polygon, Avalanche, Ethereum, Base, Base Sepolia, and Solana. # AP2 Protocol Source: https://docs.mag3nt.com/protocols/ap2 Agent-to-Agent protocol with spending mandates. ## Overview The AP2 (Agent-to-Agent Protocol) is designed for multi-agent systems where agents need to pay each other, or where a primary "orchestrator" agent needs to delegate spending authority to sub-agents. It extends the W3C Payment Headers by introducing the concept of **Mandates**. ## Spending Mandates Instead of generating a new payment card for every sub-agent, you can create a mandate on an existing card. A mandate acts as a constrained allowance: "Agent B can spend up to \$10/day from Agent A's card." ```typescript theme={null} // Create a mandate for a sub-agent const mandate = await mag3nt.ap2.ap2CreateMandate({ cardId: "sx_...", cardToken: "tok_...", maxAmount: 10, period: "daily", grantee: "0xAgentB...", }); ``` When the sub-agent needs to execute a payment on behalf of the orchestrator, it executes against the mandate: ```typescript theme={null} // Sub-agent executes payments against the mandate const payment = await mag3nt.ap2.ap2Execute({ mandateId: mandate.mandateId, amount: 2.50, description: "Data processing fee", }); ``` ## Receiving AP2 Payments If you are an agent receiving payment from another agent, you issue an AP2 challenge containing a `grantee` requirement. AP2 provides native primitives for dispute resolution and refunds, making it ideal for untrusted agent swarms where verifiable work must be completed before final settlement occurs. # MPP Protocol Source: https://docs.mag3nt.com/protocols/mpp The Machine Payment Protocol for autonomous agents and micropayments. ## Overview The [Machine Payment Protocol (MPP)](https://mpp.dev) is a lightweight, Push-based payment standard designed for high-frequency agent interactions. It sits on top of standard [W3C HTTP Payment Headers](/protocols/w3c). Unlike x402 (which uses a Pull model where the merchant executes the transfer), MPP operates on a **Push** model. The agent broadcasts the transfer on-chain, and hands the merchant the transaction hash as proof. The merchant simply verifies the hash exists on-chain and unlocks the resource. ## How mag3nt Handles MPP Because MPP is a Push protocol, mag3nt acts as a **pure payment rail** for MPP endpoints, completely removing itself from your agent's data path. When your agent hits an MPP endpoint, pass the URL to mag3nt: ```typescript theme={null} // 1. Agent calls an API, gets 402 // 2. Pay via mag3nt const payment = await mag3nt.payments.paymentsExecute({ cardId: "sx_...", cardToken: "tok_...", url: "https://api.example.com/data", }); // 3. mag3nt broadcasts the transaction and returns the cryptographic receipt console.log(payment.credential.header_name); // "Authorization" console.log(payment.credential.header_value); // "Payment eyJjaGFs..." // 4. Your agent replays the request with the receipt! const response = await fetch("https://api.example.com/data", { headers: { [payment.credential.header_name]: payment.credential.header_value } }); ``` Behind the scenes: 1. mag3nt parses the `WWW-Authenticate: Payment` challenge. 2. mag3nt executes the on-chain transfer to the merchant via CDP. 3. mag3nt constructs the MPP `Authorization: Payment` credential containing the transaction `hash` (`type: "hash"`). 4. mag3nt hands the credential back to your agent. This architecture ensures that if your agent is downloading a 5GB file, maintaining a persistent WebSocket, or streaming an LLM response, mag3nt never has to proxy or buffer that data. ## Streaming Micropayments MPP's lightweight nature makes it perfect for streaming micropayments (pay-per-token, pay-per-API-call). mag3nt supports continuous payment channels over MPP: ```typescript theme={null} // Open stream with $5 budget const stream = await mag3nt.mpp.mppStreamsOpen({ payerCardId: "sx_payer...", payerCardToken: "tok_...", receiverCardId: "sx_receiver...", budget: 5.0, }); // Send micro-payments as resources are consumed await mag3nt.mpp.mppStreamsTick({ streamId: stream.stream.id, amount: 0.001, resource: "token-generation", }); // Check running totals const status = await mag3nt.mpp.mppStreamsGet(stream.stream.id); console.log(`Spent: ${status.stream.totalSettled} / ${status.stream.budget}`); // Close when done await mag3nt.mpp.mppStreamsClose({ streamId: stream.stream.id }); ``` ## Finding MPP Services You can discover APIs and agents that accept MPP payments by browsing the [MPP Services Directory](https://mpp.dev/services). ## Receiving MPP Payments & Pay Links If you are building a service that accepts MPP, you must throw a `402 Payment Required` with a `WWW-Authenticate: Payment` challenge. To make this frictionless, mag3nt supports **Pay Links**. You can inject a mag3nt Pay Link directly into your MPP challenge via the `settleUrl` extension. This allows agents to pay you instantly, while also providing a fallback URL for humans to pay via a web UI. # W3C Payment Headers Source: https://docs.mag3nt.com/protocols/w3c The HTTP standard that powers mag3nt's protocols. ## Overview The protocols supported by mag3nt (MPP, AP2, and x402) all rely on the standard HTTP `402 Payment Required` status code, originally defined in HTTP/1.1 (RFC 7231). To negotiate and settle payments over HTTP, these protocols use the standard W3C header format: * **`WWW-Authenticate: Payment`**: Sent by the server to challenge the client for payment. * **`Authorization: Payment`**: Sent by the client (agent) as proof of payment to unlock the resource. This is the transport layer that makes machine-to-machine payments possible. ## The Challenge (`WWW-Authenticate`) When an agent attempts to access a paid resource without valid payment, the server responds with a `402 Payment Required` and a challenge header. ```http theme={null} HTTP/1.1 402 Payment Required WWW-Authenticate: Payment id="chal_123", realm="api.example.com", method="mpp", intent="charge", request="base64url_encoded_payload" ``` ### Anatomy of a Challenge | Parameter | Description | | --------- | ------------------------------------------------------------------------------------------- | | `id` | A unique identifier for the challenge. | | `realm` | The domain or namespace of the resource. | | `method` | The accepted payment protocol (e.g., `x402`, `mpp`, `ap2`). | | `intent` | Typically `charge` or `authorize`. | | `request` | A base64url-encoded payload containing the price, currency, network, and recipient details. | The `request` payload varies by method. For example, an MPP payload might decode to: ```json theme={null} { "amount": 100000, "currency": "USDC", "recipient": "0xYourAddress", "methodDetails": { "chainId": 8453 } } ``` ## The Receipt (`Authorization`) After the agent's wallet (or mag3nt's Universal Payment Engine) settles the payment on-chain, the agent retries the request with an `Authorization` header containing the cryptographic proof. ```http theme={null} GET /resource HTTP/1.1 Host: api.example.com Authorization: Payment eyJjaGFsbGVuZ2UiOiB7... ``` The credential is a base64url-encoded JSON object that echoes the original challenge and includes a `payload` with the settlement proof (e.g., a transaction hash for Push payments, or a signature for Pull payments). ```json theme={null} { "challenge": { "id": "chal_123", "method": "mpp" }, "payload": { "type": "hash", "hash": "0xabcd1234..." }, "source": "did:pkh:eip155:8453:0xAgentAddress" } ``` ## How mag3nt Handles This You don't have to manually parse these headers when making outbound payments. When your agent hits a `402`, you pass the target URL to mag3nt's universal `payments.execute` endpoint. mag3nt automatically probes the URL, reads the `WWW-Authenticate` header, decodes the `request`, executes the on-chain transfer, and returns the signed `Authorization: Payment` credential for your agent to use. ## Live Demo We built a live **Adverse Media Screening** demo to showcase the standard W3C header-based flow in action: * **Live URL**: [mag3nt-screen-demo.vercel.app](https://mag3nt-screen-demo.vercel.app/) * **GitHub Repository**: [mag3nt-com/mag3nt-screen-demo](https://github.com/mag3nt-com/mag3nt-screen-demo) The demo serves as a resource server that protects its screening API with `402 Payment Required` headers. You can configure your agent with a mag3nt card, query the screening API, handle the challenge, and unlock the resource. The repository provides a reference implementation for constructing W3C payment challenges and verifying agent payments on-chain. # x402 Protocol Source: https://docs.mag3nt.com/protocols/x402 The Coinbase-backed standard for API monetization. ## Overview [x402](https://x402.org) is a payment protocol designed for monetizing AI and API access. It operates on a **Pull** model, leveraging EIP-3009 (`TransferWithAuthorization`) to allow the merchant to pull funds directly from the agent's wallet. When an agent requests an x402-protected resource, the server rejects the request with a `402 Payment Required` and a challenge detailing the price and network. The agent signs an authorization for that amount and replays the request. The merchant's server validates the signature, submits it to the blockchain to pull the funds, and returns the resource. ## How mag3nt Handles x402 Because x402 requires the agent to physically deliver a cryptographic signature to the merchant *before* the merchant will unlock the resource, our Universal Payment Engine (`payments.execute`) acts as a **content proxy** for x402 endpoints. When your agent hits an x402 endpoint, pass the URL to mag3nt: ```typescript theme={null} // 1. Agent calls an API, gets 402 // 2. Pay via mag3nt const payment = await mag3nt.payments.paymentsExecute({ cardId: "sx_...", cardToken: "tok_...", url: "https://weather-api.com/forecast", }); // 3. For x402, mag3nt automatically replays the request with the signature // and returns the actual resource! console.log(payment.resource); // { forecast: "Sunny" } ``` Behind the scenes: 1. mag3nt parses the x402 challenge (either from a `Payment-Required` header, an `X-Payment` header, or a JSON body). 2. mag3nt signs an EIP-3009 `TransferWithAuthorization` using your treasury EOA. 3. mag3nt replays the request to the merchant with the signature in the `X-PAYMENT` header. 4. The merchant accepts the signature, settles the payment on-chain, and returns the resource to mag3nt. 5. mag3nt returns the resource to your agent. ### Supported x402 Chains mag3nt supports x402 settlement across the following networks: * Tempo * Solana * Base ## Finding x402 Services You can discover APIs and agents that accept x402 payments by browsing the [x402 Resources Directory](https://www.x402scan.com/resources). ## Receiving x402 Payments If you are building an API that *accepts* x402, you must issue a `402 Payment Required` challenge containing your pricing requirements. When the agent retries with their `X-PAYMENT` signature, you must verify the EIP-3009 signature, ensure the nonce hasn't been used, and submit it on-chain to pull the funds before returning the resource. # Quickstart Source: https://docs.mag3nt.com/quickstart Issue your first virtual card and make a payment in 5 minutes. ## 1. Get an API key Sign in at [mag3nt.com](https://mag3nt.com) with your wallet, then generate an API key from the dashboard. ```bash theme={null} # Your key looks like this: mag3nt_live_a1b2c3d4e5f6g7h8i9j0... ``` ## 2. Install the SDK ```bash npm theme={null} npm install @mag3nt/sdk ``` ```bash pip theme={null} pip install mag3nt ``` ## 3. Initialize the client ```typescript TypeScript theme={null} import { Mag3nt } from "@mag3nt/sdk"; const mag3nt = new Mag3nt({ serverURL: "https://mag3nt.com", security: { bearerAuth: "mag3nt_live_your_api_key_here", }, }); ``` ```python Python theme={null} import mag3nt from mag3nt.models.components import Security sdk = mag3nt.Mag3nt( server_url="https://mag3nt.com", security=Security(bearer_auth="mag3nt_live_your_api_key_here"), ) ``` ## 4. Fund your treasury Send USDC or pathUSD to your treasury address (e.g. Base, Solana, or Tempo). Check your balance: ```typescript TypeScript theme={null} const config = await mag3nt.status.statusGetConfig(); console.log("Treasury address:", config.treasury?.evm); // Send USDC/pathUSD to this address const balance = await mag3nt.funding.fundingGetBalance(); console.log("Available:", balance.balances); ``` ```python Python theme={null} config = sdk.status.status_get_config() print("Treasury address:", config.treasury.evm) # Send USDC/pathUSD to this address balance = sdk.funding.funding_get_balance() print("Available:", balance.balances) ``` ## 5. Issue a card ```typescript TypeScript theme={null} const card = await mag3nt.cards.cardsCreate({ purpose: "Research Agent", limitAmount: 50, network: "eip155:8453", asset: "USDC", }); console.log("Card ID:", card.card?.id); console.log("Card Token:", card.card?.token); console.log("Status:", card.card?.status); ``` ```python Python theme={null} card = sdk.cards.cards_create( purpose="Research Agent", limit_amount=50, network="eip155:8453", asset="USDC", ) print("Card ID:", card.card.id) print("Card Token:", card.card.token) print("Status:", card.card.status) ``` ## 6. Make a payment Use your card to make a payment. mag3nt. automatically detects the protocol (x402, MPP, or AP2) and settles on-chain: ```typescript TypeScript theme={null} const payment = await mag3nt.payments.paymentsExecute({ cardId: card.card.id, cardToken: card.card.token, url: "https://api.weather.com/forecast", }); console.log("Payment successful:", payment.transactionId); ``` ```python Python theme={null} payment = sdk.payments.payments_execute( card_id=card.card.id, card_token=card.card.token, url="https://api.weather.com/forecast", ) print("Payment successful:", payment.transaction_id) ``` ## Next steps MCC locks, single-use cards, spending limits How 402 payment challenges work Deposits, balance, multi-network support All 42 endpoints with interactive examples # Python SDK Source: https://docs.mag3nt.com/sdks/python Install and configure the mag3nt Python SDK. ## Installation ```bash theme={null} pip install mag3nt ``` ## Setup ```python theme={null} import mag3nt from mag3nt.models.components import Security import os sdk = mag3nt.Mag3nt( server_url="https://mag3nt.com", security=Security(bearer_auth=os.environ["MAG3NT_API_KEY"]), ) ``` ## Usage ```python theme={null} # Issue a card card = sdk.cards.cards_create( purpose="Research Agent", limit_amount=50, ) # Check balance balance = sdk.funding.funding_get_balance() # Pay for an API payment = sdk.payments.payments_execute( card_id=card.card.id, card_token=card.card.token, url="https://api.weather.com/forecast" ) # List transactions txns = sdk.cards.cards_list_transactions(id=card.card.id) ``` ## Async support Every method has an async variant with the `_async` suffix: ```python theme={null} import asyncio async def main(): cards = await sdk.cards.cards_list_async() balance = await sdk.funding.funding_get_balance_async() asyncio.run(main()) ``` ## Error handling ```python theme={null} from mag3nt.models.errors import BalanceError, Mag3ntError try: sdk.cards.cards_create(purpose="Agent", limit_amount=100) except BalanceError as e: print(f"Need {e.requested}, have {e.available}") except Mag3ntError as e: print(f"Error: {e.status_code}") ``` ## Available methods | Module | Description | | ---------------- | ----------------------------------------- | | `sdk.keys` | API key management | | `sdk.cards` | Card issuance, controls, and transactions | | `sdk.funding` | Balance and deposits | | `sdk.payments` | Universal outbound payment engine | | `sdk.x402` | x402 protocol payments (deprecated) | | `sdk.ap2` | Agent-to-agent payments | | `sdk.mpp` | Micropayment streaming | | `sdk.pay_links` | Shareable payment links | | `sdk.settlement` | Settlement status | | `sdk.status` | Platform health | See the [API Reference](/api-reference/cards/list-all-cards-for-the-authenticated-wallet) for full method documentation. # TypeScript SDK Source: https://docs.mag3nt.com/sdks/typescript Install and configure the mag3nt TypeScript SDK. ## Installation ```bash npm theme={null} npm install @mag3nt/sdk ``` ```bash pnpm theme={null} pnpm add @mag3nt/sdk ``` ```bash yarn theme={null} yarn add @mag3nt/sdk ``` ## Setup ```typescript theme={null} import { Mag3nt } from "@mag3nt/sdk"; const mag3nt = new Mag3nt({ serverURL: "https://mag3nt.com", security: { bearerAuth: process.env.MAG3NT_API_KEY, }, }); ``` ## Usage ```typescript theme={null} // Issue a card const card = await mag3nt.cards.cardsCreate({ purpose: "Research Agent", limitAmount: 50, }); // Pay for an API const payment = await mag3nt.payments.paymentsExecute({ cardId: card.card.id, cardToken: card.card.token, url: "https://api.weather.com/forecast", }); // Check balance const balance = await mag3nt.funding.fundingGetBalance(); ``` ## Error handling ```typescript theme={null} import * as errors from "@mag3nt/sdk/models/errors"; try { await mag3nt.cards.cardsCreate({ purpose: "Agent", limitAmount: 100 }); } catch (error) { if (error instanceof errors.BalanceError) { console.log(`Need ${error.data$.requested}, have ${error.data$.available}`); } } ``` ## Available methods | Module | Description | | ------------------- | ----------------------------------------- | | `mag3nt.keys` | API key management | | `mag3nt.cards` | Card issuance, controls, and transactions | | `mag3nt.funding` | Balance and deposits | | `mag3nt.payments` | Universal outbound payment engine | | `mag3nt.x402` | x402 protocol payments (deprecated) | | `mag3nt.ap2` | Agent-to-agent payments | | `mag3nt.mpp` | Micropayment streaming | | `mag3nt.payLinks` | Shareable payment links | | `mag3nt.settlement` | Settlement status | | `mag3nt.status` | Platform health | See the [API Reference](/api-reference/cards/list-all-cards-for-the-authenticated-wallet) for full method documentation.