Quickstart: developers and AI agents

Get an API key, make your first call, then connect an AI assistant or give an AI agent its own card.

In sandbox

SorenPay is in private beta. Every workspace runs in sandbox: everything below works with test money, and nothing moves real money. Live accounts open to US businesses first, starting with the USD account. See the docs overview for the status of each part.

1. Get access

Sign-ups aren't open yet. Join the early-bird list on the sign-in page. Beta testers sign in at the link we sent them, and pick Business to get a workspace.

2. Create an API key in the dashboard

In a sandbox workspace, open Developers in the dashboard (or go straight to API keys) and choose Create key. Only workspace owners and admins can create one.

The key's secret (apk_…) is shown once. It has a fixed set of scopes, the ones the dashboard's own forms use:

Scope	What it lets the key do
`read:treasury`	Balances, the ledger, currency balances, conversions
`write:treasury`	Sandbox test deposits; currency quotes and conversions
`read:cards`, `write:cards`	List and create cards
`write:agents`	Register AI agents and submit their payment intents
`read:checkout`, `write:checkout`	Checkout sessions
`read:api_keys`	List your workspace's keys

It can't create other keys, send payouts (write:payouts), save recipients (write:counterparties), use the USDC ramp (write:ramps) or list agents (read:agents). The key shown once at business onboarding only manages keys: a key can only hand out scopes it holds itself, so it can't create a key with any of the scopes above. For a key with other scopes, ask support@sorenpay.com.

Treat it as a secret

Store the key where your code can read it, such as a secret manager or an environment variable, and never commit it. Revoking a key from the dashboard isn't available yet: if one leaks, email support@sorenpay.com to revoke it. See Authentication for scopes, rate limits and idempotency.

3. Make your first API call

Every request carries the key as a bearer token. The base URL is https://sorenpay.com.

Your USD accountbash

read -rs SOREN_API_KEY   # paste the key from step 2, then Enter (not echoed)

curl https://sorenpay.com/api/treasury \
-H "Authorization: Bearer $SOREN_API_KEY"

balances lists each account with its Available, Incoming and Held amounts. The USD account is the fiat one; a stablecoin balance, if any, is listed apart from it and never added to it. ledger is the recent ledger.

{
"balances": [ … ],
"snapshot": { … },
"ledger": []
}

snapshot is an older summary kept for existing integrations. Read balances instead.

Your currency balances are a separate ledger with their own endpoint (in sandbox):

Your currency balancesbash

curl https://sorenpay.com/api/mca/accounts \
-H "Authorization: Bearer $SOREN_API_KEY"

See Multi-currency for opening a balance and adding test money. Converting between balances is coming soon.

4. Create a card and try a payment

A card with limitsbash

curl -X POST https://sorenpay.com/api/cards \
-H "Authorization: Bearer $SOREN_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
  "holderKind": "agent",
  "holderLabel": "research-agent",
  "monthlyLimitUsdCents": 50000,
  "perTxnLimitUsdCents": 5000,
  "allowedMccs": ["7372"]
}'

The response is { card, fixture }. In sandbox, fixture: true means the card is a test stand-in, not a card from our card issuing partner.

To see the limits work, open the card in the dashboard and use the Try a test payment panel. It shows whether the payment is approved or declined, and why. The panel is sandbox only.

5. For AI agents

There are two ways to use AI with SorenPay, and they need different things.

Connect an AI assistant (MCP)

An assistant such as Claude or Cursor can read your account over MCP and answer questions like "How much can we spend?". Every tool is read-only: it can look, not move money. The server is POST https://sorenpay.com/api/mcp, and it signs in with an API key.

Claude Codebash

claude mcp add --transport http soren-pay https://sorenpay.com/api/mcp \
--header "Authorization: Bearer $SOREN_API_KEY"

The dashboard key from step 2 works with every tool except list_agents, which needs read:agents. For Claude Desktop, Cursor and other clients, see MCP setup.

Give an agent its own key and card

An agent gets its own Ed25519 key pair (POST /api/agents, scope write:agents) and signs each payment intent it wants to make. Give it a card with holderKind: "agent" (step 4): every card payment is checked against that card's limits. See the agent quickstart.

What's next

Authentication: scopes, rate limits, idempotency
Multi-currency: currency balances (in sandbox); converting is coming soon
Stablecoins: USDC, checkout, and what's coming
Card capabilities: what's built and what isn't
API reference: every route, plus the OpenAPI spec

← All docs