Skip to main content
POST
/
api
/
start-payment-session
Start an x402 payment session
curl --request POST \
  --url http://localhost:3773/api/start-payment-session \
  --header 'Authorization: Bearer <token>'
{
  "session_id": "ps_01H8...",
  "status": "pending",
  "amount": "0.01",
  "asset": "USDC",
  "network": "base-sepolia",
  "pay_to": "0x2654bb8B272f117c514aAc3d4032B1795366BA5d",
  "created_at": "2026-04-19T18:00:00+00:00",
  "expires_at": "2026-04-19T18:05:00+00:00",
  "capture_url": "https://agent.example.com/payment-capture?session_id=ps_01H8..."
}

Authorizations

​
Authorization
string
header
required

OAuth2 access token issued by Ory Hydra. Required for most operations.

Scopes:

  • agent:read — Read-only operations (tasks/get, tasks/list, contexts/list)
  • agent:write — Write operations (message/send, tasks/cancel, contexts/clear)
  • agent:execute — (legacy) Both read and write access

How to obtain:

  1. Register your client with Hydra
  2. Complete OAuth2 client credentials or authorization code flow
  3. Include token in Authorization: Bearer <token> header

Response

200 - application/json

Payment session opened

​
session_id
string
required
​
status
enum<string>
required
Available options:
pending,
completed,
failed,
expired
​
amount
string
required

Amount as string to avoid float precision

​
asset
string
required
Example:

"USDC"

​
network
string
required
Example:

"base-sepolia"

​
pay_to
string
required

Wallet address to pay

​
created_at
string<date-time>
required
​
expires_at
string<date-time>
​
capture_url
string<uri>

Human-facing payment URL