Argens API Documentation
Argens is a programmable payment infrastructure for AI agents. One API key gives your agent a USDC wallet on Stellar, three human-defined spending rules, cross-chain settlement to Base via CCTP V2, and access to a paid marketplace of 80+ AI services — all without blockchain knowledge.
Quickstart — zero to live in five steps.
No blockchain knowledge required. No SDK to install. Your agent needs nothing but an API key.
Sign up at argens.xyz. You'll receive a verification email. Argens automatically creates and funds a Stellar wallet with USDC trustline on signup — 2 XLM absorbed on your behalf, nothing to configure.
Send USDC to your Stellar wallet address. Use any Stellar-compatible wallet (Lobstr, StellarX, your exchange's Stellar withdrawal). Argens detects the deposit and emails you a confirmation.
Configure three rules in the dashboard: a monthly allowance (total spend cap), a per-transaction maximum (blocks any single large payment), and an approval threshold (pauses payments above a certain size for your review).
Go to the API Keys page. Your key has the prefix argns_live_ and is shown once. Argens stores only a bcrypt hash — if you lose it, regenerate. Give the key to your agent as an environment variable.
Call POST /pay with a Stellar G... address for a direct Stellar payment, or a 0x... EVM address for a cross-chain USDC transfer to Base via CCTP V2. No additional configuration needed.
Two auth paths. Never mix them.
Agent routes use API keys. Dashboard routes use the session JWT. They are separate by design — agent spend and human-initiated spend have different trust models.
argns_live_… key is the only credential an agent needs. Pass it as Authorization: Bearer <key>. Never expires unless you explicitly regenerate. Access: /pay, /quote, /agent/status, /transactions, /marketplace/call, /marketplace/services./wallet/send) require JWT auth — not callable with an API key. This keeps agent spend and manual transfers on separate audit trails.The key is a credential. Never include it in logs, traces, error messages, or responses. Argens stores only a bcrypt hash — the raw key is unrecoverable after creation.
Set ARGENS_KEY as an environment variable, not hardcoded. For hosted agents, use the secret manager provided by your cloud platform.
The API Keys page lets you regenerate at any time. The old key is immediately revoked. Keep the new key safe — it's shown once.
Send USDC to Stellar or Base in one call.
POST /pay auto-detects the destination chain from the recipient address format. A G… address routes to Stellar directly. A 0x… address routes through Circle CCTP V2 and mints USDC natively on Base. Same endpoint — no chain: param needed.
"25.0000000" not 25. This applies to requests, responses, and polling results. Parsing amounts as numbers introduces float errors.Three rules. Every payment runs through all three.
Policies are the core of Argens. They run in order — earliest failure wins — on every /pay call and every marketplace call. There is no way to bypass them from the agent side.
cost_paid amount logged on the transaction.Human in the loop — without breaking the agent.
When a payment hits the approval_threshold, Argens doesn't fail the request — it pauses it. The agent gets a 202 with a poll URL. You get an email with a one-click confirmation page. The agent resumes when you approve.
Amount meets or exceeds approval_threshold. Policy check returns PENDING_APPROVAL.
Transaction created with status PENDING_APPROVAL. A 24-hour single-use token is generated.
You receive an email with a link to the dashboard confirmation page — not a direct action URL. Email scanners cannot accidentally approve.
The agent polls at a reasonable cadence. Status is PENDING_APPROVAL until you act. No timeout on the agent side — approval can take up to 24h.
The dashboard shows full transaction detail. You click Approve or Reject. On approval, Argens re-runs the policy check and executes the payment.
Next poll returns SUCCESS (with stellar_tx_hash) or REJECTED. The agent continues its loop.
GET /approve/:token link would be triggered accidentally. The email contains only a link to the dashboard confirmation page. Approval requires a button click.80+ AI services. One API key. Zero subscriptions.
Call any enabled provider by service ID. Argens handles the upstream API call, debits the cost from your wallet, runs the full policy check, and logs the transaction. Your agent needs no separate accounts or API keys.
/SKILL/{provider_id}.md for any enabled provider to get a concise usage reference your agent can load as context before making calls. No external documentation to find.The same three policies — max transaction, allowance, approval threshold — apply to marketplace calls exactly as they do to direct payments. Agents cannot bypass policy limits by routing through the marketplace. The cost_paid field on the transaction record is what policy checks against.
One prompt. Any agent. Under 60 seconds.
The fastest way to onboard an AI agent is to give it the SKILL.md URL as context. The agent reads the full API surface, asks for your key, and is ready to spend. No SDK, no install, no boilerplate.
The primary agent onboarding payload. Full API surface, authentication instructions, response shapes, error codes, and amount format rules — all in one file under 6,000 tokens. Versioned.
Per-provider usage reference for marketplace endpoints. The agent fetches this after discovering a provider in /marketplace/services. Shows exact payload shapes and response formats.
Discovery index for LLM tools and crawlers. Points to SKILL.md, the docs page, the API catalog, and the provider skill URL pattern. Follows the emerging llms.txt convention.
Every response uses the same envelope.
Success is { "data": ... }. Error is { "error": "...", "code": "...", "details": ... }. No exceptions. The meta field appears on paginated responses only.
Machine-readable codes for every failure mode.
Every error response includes a code field. Use it to handle failures programmatically — not the human-readable error string, which may change.
Hard limits and security model.
Reference for building robust agents and integrations.
Argens holds your encrypted Stellar signing key so agents can spend autonomously. The key is AES-256-GCM encrypted at rest. You can export it anytime from the dashboard.
Secret keys are never returned in responses, never logged, and decrypted only in memory for the duration of signing.
Your API key is shown once on creation. Argens stores only a bcrypt hash. The original is unrecoverable — regenerate if lost.
Magic links go to a dashboard confirmation page, not a direct action endpoint. Email scanners cannot accidentally approve a payment.
Create a free account, fund a wallet, and your agent can be spending in under 5 minutes. No blockchain knowledge required.