> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentwallex.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create x402 Session
> Create a new x402 payment session with a spending budget.
Sessions let you pre-authorize a spending budget for repeated x402 API calls. Payments within a session are deducted from the session budget without requiring individual approval for each call.
### Request Body
The agent whose wallet funds the session.
Maximum total amount the session can spend (e.g., `"100.00"`).
CAIP-2 chain identifier for settlement (e.g., `eip155:84532`).
Session time-to-live in seconds. The session expires after this duration.
Optional list of URLs this session is authorized to pay. If omitted, all x402-enabled URLs are allowed.
### Example
```bash cURL theme={null}
curl -X POST https://api.agentwallex.com/api/v1/x402/sessions \
-H "X-API-Key: awx_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"agent_id": "agent_abc123",
"budget_limit": "100.00",
"chain": "eip155:84532",
"ttl_seconds": 3600,
"allowed_urls": ["https://paid-api.example.com/v1/data"]
}'
```
```typescript TypeScript theme={null}
const session = await aw.x402.createSession({
agentId: "agent_abc123",
budgetLimit: "100.00",
chain: "eip155:84532",
ttlSeconds: 3600,
allowedUrls: ["https://paid-api.example.com/v1/data"],
});
```
```python Python theme={null}
session = await aw.x402.create_session(
agent_id="agent_abc123",
budget_limit="100.00",
chain="eip155:84532",
ttl_seconds=3600,
allowed_urls=["https://paid-api.example.com/v1/data"],
)
```
```json Response theme={null}
{
"id": "sess_xyz789",
"agent_id": "agent_abc123",
"budget_limit": "100.00",
"budget_spent": "0.00",
"budget_remaining": "100.00",
"chain": "eip155:84532",
"status": "active",
"expires_at": "2025-06-15T15:30:00Z",
"created_at": "2025-06-15T14:30:00Z"
}
```
## OpenAPI
````yaml POST /api/v1/x402/sessions
openapi: 3.1.0
info:
title: AgentWallex API
description: >-
REST API for managing AI agent wallets, on-chain transactions, spending
policies, webhooks, and x402 micropayments.
version: 1.0.0
contact:
name: AgentWallex Support
url: https://agentwallex.com
servers:
- url: https://api.agentwallex.com
description: Production
- url: https://api-sandbox.agentwallex.com
description: Sandbox
security:
- ApiKeyAuth: []
- BearerAuth: []
tags:
- name: Agents
description: Create and manage AI agent wallets.
- name: Transactions
description: Send payments and query transaction history.
- name: Policies
description: Configure spending limits and access controls.
- name: Webhooks
description: Register and manage webhook endpoints.
- name: x402
description: x402 micropayment negotiation and session management.
paths:
/api/v1/x402/sessions:
post:
tags:
- x402
summary: Create x402 Session
description: >-
Create a new x402 payment session with a spending budget. Sessions let
you pre-authorize a spending budget for repeated x402 API calls.
Payments within a session are deducted from the session budget without
requiring individual approval for each call.
operationId: createX402Session
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- agent_id
- budget_limit
- chain
- ttl_seconds
properties:
agent_id:
type: string
description: The agent whose wallet funds the session.
budget_limit:
type: string
description: >-
Maximum total amount the session can spend (e.g.,
`"100.00"`).
chain:
type: string
description: >-
CAIP-2 chain identifier for settlement (e.g.,
`eip155:84532`).
ttl_seconds:
type: integer
description: >-
Session time-to-live in seconds. The session expires after
this duration.
allowed_urls:
type: array
items:
type: string
format: uri
description: >-
Optional list of URLs this session is authorized to pay. If
omitted, all x402-enabled URLs are allowed.
example:
agent_id: agent_abc123
budget_limit: '100.00'
chain: eip155:84532
ttl_seconds: 3600
allowed_urls:
- https://paid-api.example.com/v1/data
responses:
'200':
description: Session created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/X402Session'
example:
id: sess_xyz789
agent_id: agent_abc123
budget_limit: '100.00'
budget_spent: '0.00'
budget_remaining: '100.00'
chain: eip155:84532
status: active
expires_at: '2025-06-15T15:30:00Z'
created_at: '2025-06-15T14:30:00Z'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/InternalError'
components:
schemas:
X402Session:
type: object
description: An x402 payment session with a pre-authorized spending budget.
properties:
id:
type: string
description: Unique session identifier (e.g., `sess_xyz789`).
agent_id:
type: string
description: Agent whose wallet funds the session.
budget_limit:
type: string
description: Maximum total amount the session can spend.
budget_spent:
type: string
description: Total amount spent so far.
budget_remaining:
type: string
description: Remaining budget available.
chain:
type: string
description: CAIP-2 chain identifier for settlement.
status:
type: string
enum:
- active
- expired
- deleted
description: Session status.
allowed_urls:
type: array
items:
type: string
format: uri
description: URLs this session is authorized to pay.
expires_at:
type: string
format: date-time
description: ISO 8601 expiration timestamp.
created_at:
type: string
format: date-time
description: ISO 8601 creation timestamp.
ErrorResponse:
type: object
description: Standard error response.
required:
- code
- type
- message
properties:
code:
type: string
description: Machine-readable error code.
type:
type: string
enum:
- invalid_request_error
- authentication_error
- authorization_error
- not_found_error
- rate_limit_error
- internal_error
description: Error type category.
message:
type: string
description: Human-readable error description.
responses:
BadRequest:
description: Invalid request body or parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
code: invalid_request
type: invalid_request_error
message: The request body is missing required fields.
Unauthorized:
description: Missing or invalid credentials.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
code: authentication_failed
type: authentication_error
message: The provided API key is invalid or expired.
Forbidden:
description: Insufficient permissions.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
code: insufficient_permissions
type: authorization_error
message: You do not have permission to perform this action.
RateLimited:
description: Rate limit exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
code: rate_limit_exceeded
type: rate_limit_error
message: Too many requests. Please retry after a short delay.
InternalError:
description: Server-side error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
code: server_error
type: internal_error
message: An unexpected error occurred. Please try again later.
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
description: API key authentication. Keys are prefixed with `awx_`.
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: JWT bearer token authentication.
````