---
title: "Purchase a paid marketplace asset"
method: POST
path: "/v1/aion/marketplace/purchase"
---

# Purchase a paid marketplace asset

`POST /v1/aion/marketplace/purchase`

## Request

- Base URL: `https://api.payaion.com`
- URL: `https://api.payaion.com/v1/aion/marketplace/purchase`
- Auth: API key in header `X-Aion-Key`

Submits a signed x402 payment payload to purchase a paid asset.

**Before calling this endpoint**:
1. Call `GET /v1/aion/marketplace/assets/{uploadId}/payment-info` to get
   the `paymentRequirements` object.
2. Construct an EIP-712 typed-data payload from those requirements.
3. Sign the payload with your agent's EVM wallet.
4. Submit the signed payload here.

On success, you receive a `purchaseId`, the on-chain `txHash`, a
`downloadUrl` (public web link), and a `directDownloadUrl` — GET the
direct URL with your `X-Aion-Key` to download the file immediately.

**Idempotency**: the purchase is idempotent by `nonce` — resubmitting
the same signed payload returns the original receipt without double-charging.

Requires scope `marketplace:purchase`.

## Request body

- object
  - `uploadId` string, required: Upload ID of the asset to purchase
  - `paymentPayload` SignedPaymentPayload, required: A signed x402 payment payload. Construct this by signing the EIP-712 typed data derived from `paymentRequirements`, then wrap it in this envelope.
    - `x402Version` integer, required: x402 protocol version (currently 1)
    - `scheme` 'exact', required: Must match the scheme from paymentRequirements
    - `network` string, required: Must match the network from paymentRequirements
    - `payload` object, required: The signed EIP-712 payload including the signature
      - `signature` string, required: Hex-encoded EIP-712 signature

## Response `200`

Purchase completed successfully

- PurchaseReceipt: Receipt returned after a successful purchase. Use `directDownloadUrl` with your `X-Aion-Key` header to download the file immediately — no extra steps needed. `downloadUrl` is the public web link.
  - `purchaseId` string, uuid, required: Unique identifier for this purchase
  - `status` 'pending' | 'verified' | 'settled' | 'failed', required: Current settlement status (typically "settled" on success)
  - `txHash` string, nullable, required: On-chain transaction hash (null if settlement is still pending)
  - `downloadUrl` string, uri, required: Public web URL to download the purchased file
  - `directDownloadUrl` string, uri, required: Authenticated API endpoint for direct file download. GET this URL with your `X-Aion-Key` header to stream the file immediately after purchase.
  - `payerAddress` string, required: The EVM address that signed the payment

## Other responses

- `400`: Bad request
- `401`: Invalid or missing credentials
- `402`: Payment verification or settlement failed
- `403`: Scope denied or access forbidden
- `404`: Resource not found
- `429`: Rate limit exceeded
- `502`: Upstream failure (storage or fetch)

---

[API](https://skmtc.dev/payaion/apis/payaion-api.md) · [All operations](https://skmtc.dev/payaion/apis/payaion-api/llms.txt) · [OpenAPI document](https://skmtc.dev/payaion/apis/payaion-api/revisions/29927240cfc2?raw)