> ## 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.
# x402 Pay
> Trigger an x402 payment negotiation for a target URL.
Negotiate and complete one x402 payment for a target URL. AgentWallex evaluates the agent's policies, signs the payment via MPC, and returns the payment info needed to access the paid resource.
## Request Body
The agent whose wallet will fund the payment.
The x402-enabled URL to pay for (e.g., `https://paid-api.example.com/v1/data`).
Optional session ID to deduct from an existing session budget. See [x402 Sessions](/api-reference/x402-sessions).
CAIP-2 chain identifier for payment settlement (e.g., `eip155:84532`). If omitted, the agent's default chain is used.
## Response
Internal ledger entry ID for this payment.
Payment amount.
Platform fee deducted.
Fee percentage applied (based on tiered pricing).
Token used for payment (e.g., `USDC`).
Chain used for settlement.
Payment status: `completed`, `pending`, `failed`.
The `PAYMENT-SIGNATURE` value to include in the retry request to the target URL.
## Example
```bash cURL theme={null}
curl -X POST https://api.agentwallex.com/api/v1/x402/pay \
-H "X-API-Key: awx_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"agent_id": "agent_abc123",
"target_url": "https://paid-api.example.com/v1/data",
"session_id": "sess_xyz789",
"chain": "eip155:84532"
}'
```
```typescript TypeScript theme={null}
const result = await aw.x402.pay({
agentId: "agent_abc123",
targetUrl: "https://paid-api.example.com/v1/data",
sessionId: "sess_xyz789",
chain: "eip155:84532",
});
```
```python Python theme={null}
result = await aw.x402.pay(
agent_id="agent_abc123",
target_url="https://paid-api.example.com/v1/data",
session_id="sess_xyz789",
chain="eip155:84532",
)
```
```json Response theme={null}
{
"ledger_id": "ldg_abc123",
"amount": "0.10",
"fee_amount": "0.002",
"fee_rate": "2.0",
"token": "USDC",
"chain": "eip155:84532",
"status": "completed",
"payment_signature": "base64_encoded_signature..."
}
```
## Related Endpoints
| Endpoint | Description |
| --------------------------------- | -------------------------------------------------- |
| `POST /x402/check` | Check if a URL supports x402 payment negotiation |
| `POST /x402/facilitator/verify` | Verify a payment signature (for service providers) |
| `POST /x402/facilitator/settle` | Settle a verified payment (for service providers) |
| `GET /x402/facilitator/supported` | List supported chains for x402 |
| `GET /x402/fees/tiers` | Get current fee tier schedule |
## OpenAPI
````yaml POST /api/v1/x402/pay
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/pay:
post:
tags:
- x402
summary: x402 Pay
description: >-
Negotiate and complete one x402 payment for a target URL. AgentWallex
evaluates the agent's policies, signs the payment via MPC, and returns
the payment info needed to access the paid resource.
operationId: x402Pay
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- agent_id
- target_url
properties:
agent_id:
type: string
description: The agent whose wallet will fund the payment.
target_url:
type: string
format: uri
description: >-
The x402-enabled URL to pay for (e.g.,
`https://paid-api.example.com/v1/data`).
session_id:
type: string
description: >-
Optional session ID to deduct from an existing session
budget.
chain:
type: string
description: >-
CAIP-2 chain identifier for payment settlement (e.g.,
`eip155:84532`). If omitted, the agent's default chain is
used.
example:
agent_id: agent_abc123
target_url: https://paid-api.example.com/v1/data
session_id: sess_xyz789
chain: eip155:84532
responses:
'200':
description: Payment completed successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/X402PayResult'
example:
ledger_id: ldg_abc123
amount: '0.10'
fee_amount: '0.002'
fee_rate: '2.0'
token: USDC
chain: eip155:84532
status: completed
payment_signature: base64_encoded_signature...
'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:
X402PayResult:
type: object
description: Result of an x402 payment negotiation.
properties:
ledger_id:
type: string
description: Internal ledger entry ID for this payment.
amount:
type: string
description: Payment amount.
fee_amount:
type: string
description: Platform fee deducted.
fee_rate:
type: string
description: Fee percentage applied (based on tiered pricing).
token:
type: string
description: Token used for payment (e.g., `USDC`).
chain:
type: string
description: Chain used for settlement.
status:
type: string
enum:
- completed
- pending
- failed
description: Payment status.
payment_signature:
type: string
description: >-
The `PAYMENT-SIGNATURE` value to include in the retry request to the
target URL.
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.
````