> ## Documentation Index
> Fetch the complete documentation index at: https://docs.x84.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Settle an x402 v2 payment (co-sign + submit to Solana)

> Verifies the payment payload, then co-signs the transaction as fee payer and submits it to Solana.

**Settlement flow:**
1. Runs the same verification as POST /verify
2. Checks for idempotency (dedup by transaction hash or paymentId)
3. Deserializes the VersionedTransaction and co-signs with the facilitator keypair (fee payer)
4. Submits the fully-signed transaction to Solana via `sendRawTransaction`
5. Confirms the transaction on-chain
6. Persists the settlement record to the database

**x84 extension modes:**
- **atomic/attestation**: Transaction is already on-chain — the facilitator just records the settlement
- **delegated (server-side)**: Vault settlement via the x84 on-chain program (pending deployment)

**Response guarantees (x402 v2):**
- `transaction` is always present (empty string on failure)
- `network` is always present (CAIP-2 identifier)



## OpenAPI

````yaml https://facilitator.x84.ai/openapi.yaml post /settle
openapi: 3.0.0
info:
  title: x84 Facilitator
  description: >-
    ## x402 v2 Payment Facilitator


    The x84 Facilitator verifies and settles USDC payments on Solana following
    the [Coinbase x402 v2 protocol](https://github.com/coinbase/x402).


    ### Endpoints


    | Method | Path | Description |

    |--------|------|-------------|

    | `GET` | `/supported` | Discover supported payment kinds, extensions, and
    signer keys |

    | `POST` | `/verify` | Verify a payment payload (deserialize tx, validate
    instructions) |

    | `POST` | `/settle` | Co-sign as fee payer and submit to Solana |


    ### x84 Extensions


    On top of standard x402 SVM exact payments, the facilitator supports
    x84-specific settlement modes via the `extensions` field:


    - **x84-atomic** — CPI receipt on-chain (tx already submitted by client)

    - **x84-attestation** — Attestation receipt on-chain

    - **x84-delegated** — Delegation-based vault settlement (client-side or
    server-side with ed25519 proof)


    ### v1 Backward Compatibility


    The `paymentPayload` field accepts both:

    - **v2 (recommended)**: Structured `PaymentPayload` object with
    `x402Version`, `accepted`, `payload`, and optional `extensions`

    - **v1 (legacy)**: Base64-encoded JSON string (automatically normalized to
    v2 internally)
  version: 0.2.0
  contact: {}
servers:
  - url: https://facilitator.x84.ai
    description: Endpoint
security: []
tags:
  - name: x402
    description: x402 v2 payment verification and settlement
externalDocs:
  description: x402 Protocol Specification
  url: https://github.com/coinbase/x402
paths:
  /settle:
    post:
      tags:
        - x402
      summary: Settle an x402 v2 payment (co-sign + submit to Solana)
      description: >-
        Verifies the payment payload, then co-signs the transaction as fee payer
        and submits it to Solana.


        **Settlement flow:**

        1. Runs the same verification as POST /verify

        2. Checks for idempotency (dedup by transaction hash or paymentId)

        3. Deserializes the VersionedTransaction and co-signs with the
        facilitator keypair (fee payer)

        4. Submits the fully-signed transaction to Solana via
        `sendRawTransaction`

        5. Confirms the transaction on-chain

        6. Persists the settlement record to the database


        **x84 extension modes:**

        - **atomic/attestation**: Transaction is already on-chain — the
        facilitator just records the settlement

        - **delegated (server-side)**: Vault settlement via the x84 on-chain
        program (pending deployment)


        **Response guarantees (x402 v2):**

        - `transaction` is always present (empty string on failure)

        - `network` is always present (CAIP-2 identifier)
      operationId: SettlementsController_settle
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SettlePaymentDto'
      responses:
        '200':
          description: Settlement result — check `success` to determine outcome
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettleResponseDto'
              examples:
                success:
                  summary: Successful settlement
                  value:
                    success: true
                    transaction: >-
                      5VERv8NMvzbJMEkV8xnrLkEaWRtSz9CosKDYjCJjBRnbJLgp8uirBgmQpjKhoR4tjF3ZpRzrFmBV6UjKdiSZkQUW
                    network: solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1
                    payer: D6j5dis544qzYmSNixwYwBXqcDqgWiFHpi6hebPEQNVu
                idempotent-hit:
                  summary: Already settled (idempotent)
                  value:
                    success: true
                    transaction: >-
                      5VERv8NMvzbJMEkV8xnrLkEaWRtSz9CosKDYjCJjBRnbJLgp8uirBgmQpjKhoR4tjF3ZpRzrFmBV6UjKdiSZkQUW
                    network: solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1
                    payer: D6j5dis544qzYmSNixwYwBXqcDqgWiFHpi6hebPEQNVu
                failure:
                  summary: Settlement failed
                  value:
                    success: false
                    transaction: ''
                    network: solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1
                    errorReason: SETTLEMENT_FAILED
                    errorMessage: 'Transaction simulation failed: insufficient funds'
                verification-failed:
                  summary: Verification failed before settlement
                  value:
                    success: false
                    transaction: ''
                    network: solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1
                    errorReason: AMOUNT_MISMATCH
                    errorMessage: Expected amount 1000000, got 500000
        '400':
          description: Malformed request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponseDto'
        '500':
          description: Facilitator configuration error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponseDto'
              examples:
                no-keypair:
                  summary: Facilitator keypair not configured
                  value:
                    statusCode: 500
                    message: Facilitator keypair not configured for settlement
                    error: Internal Server Error
components:
  schemas:
    SettlePaymentDto:
      type: object
      properties:
        paymentPayload:
          description: >-
            x402 v2 structured PaymentPayload object. For backward
            compatibility, a base64-encoded v1 proof string is also accepted.
          allOf:
            - $ref: '#/components/schemas/PaymentPayloadDto'
        paymentRequirements:
          description: >-
            The payment requirements issued by the resource server in the 402
            response
          allOf:
            - $ref: '#/components/schemas/PaymentRequirementsDto'
      required:
        - paymentPayload
        - paymentRequirements
    SettleResponseDto:
      type: object
      properties:
        success:
          type: boolean
          description: Whether the settlement succeeded
          example: true
        transaction:
          type: string
          description: >-
            Solana transaction signature (empty string on failure). REQUIRED per
            x402 v2.
          example: >-
            5VERv8NMvzbJMEkV8xnrLkEaWRtSz9CosKDYjCJjBRnbJLgp8uirBgmQpjKhoR4tjF3ZpRzrFmBV6UjKdiSZkQUW
        network:
          type: string
          description: >-
            CAIP-2 network identifier where settlement occurred. REQUIRED per
            x402 v2.
          example: solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1
        errorReason:
          type: string
          description: Machine-readable error reason code
          example: SETTLEMENT_FAILED
        errorMessage:
          type: string
          description: Human-readable error message
          example: 'Transaction simulation failed: insufficient funds'
        payer:
          type: string
          description: Wallet address of the payer
          example: D6j5dis544qzYmSNixwYwBXqcDqgWiFHpi6hebPEQNVu
        extensions:
          type: object
          description: Additional extension data
          example:
            mode: atomic
      required:
        - success
        - transaction
        - network
    BadRequestResponseDto:
      type: object
      properties:
        statusCode:
          type: number
          example: 400
        message:
          type: object
          description: Error message or array of validation messages
          example: >-
            paymentPayload must be a v2 PaymentPayload object or a
            base64-encoded v1 proof string
        error:
          type: string
          example: Bad Request
      required:
        - statusCode
        - message
        - error
    InternalServerErrorResponseDto:
      type: object
      properties:
        statusCode:
          type: number
          example: 500
        message:
          type: string
          example: Facilitator keypair not configured for settlement
        error:
          type: string
          example: Internal Server Error
      required:
        - statusCode
        - message
        - error
    PaymentPayloadDto:
      type: object
      properties:
        x402Version:
          type: number
          description: x402 protocol version
          example: 1
        resource:
          type: string
          description: Resource URL being paid for
          example: https://api.x84.ai/a2a/agent-abc/tasks/send
        accepted:
          description: The payment requirements that were accepted by the client
          allOf:
            - $ref: '#/components/schemas/PaymentRequirementsDto'
        payload:
          description: SVM exact scheme payload containing the partially-signed transaction
          allOf:
            - $ref: '#/components/schemas/SvmExactPayloadDto'
        extensions:
          description: x84-specific payment extensions (settlement mode, receipt PDA, etc.)
          allOf:
            - $ref: '#/components/schemas/X84PaymentExtensionsDto'
      required:
        - x402Version
        - accepted
        - payload
    PaymentRequirementsDto:
      type: object
      properties:
        scheme:
          type: string
          description: Payment scheme identifier
          example: exact
          enum:
            - exact
        network:
          type: string
          description: CAIP-2 network identifier
          example: solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1
        asset:
          type: string
          description: Token mint address (e.g. USDC)
          example: Gh9ZwEmdLJ8DscKNTkTqPbNwLNNBjuSzaG9Vp2KGtKJr
        amount:
          type: string
          description: Amount in token base units (e.g. 1000000 = 1 USDC)
          example: '1000000'
        payTo:
          type: string
          description: Recipient wallet address (base58)
          example: 8VF2ZAp9C1RKeV2XmKBnCQdbhGuNZaLZ1x7mTCSGsMH9
        maxTimeoutSeconds:
          type: number
          description: Maximum time in seconds before the payment expires
          example: 60
        resource:
          type: string
          description: Resource URL being paid for
          example: https://api.x84.ai/a2a/agent-abc/tasks/send
        description:
          type: string
          description: Human-readable description of the payment
          example: Query agent-abc for market analysis
        extra:
          description: Scheme-specific extra fields and x84 extensions
          allOf:
            - $ref: '#/components/schemas/PaymentRequirementsExtraDto'
      required:
        - scheme
        - network
        - asset
        - amount
        - payTo
    SvmExactPayloadDto:
      type: object
      properties:
        transaction:
          type: string
          description: >-
            Base64-encoded Solana VersionedTransaction (partially signed by
            payer)
          example: >-
            AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABjwuBdojnm...
      required:
        - transaction
    X84PaymentExtensionsDto:
      type: object
      properties:
        mode:
          type: string
          description: x84 settlement mode
          enum:
            - atomic
            - attestation
            - delegated
          example: atomic
        receiptPda:
          type: string
          description: On-chain receipt PDA address
          example: 4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU
        delegationPda:
          type: string
          description: On-chain delegation PDA address
          example: 9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin
        delegate:
          type: string
          description: Delegate wallet address (for delegated mode)
          example: D6j5dis544qzYmSNixwYwBXqcDqgWiFHpi6hebPEQNVu
        signature:
          type: string
          description: Base64-encoded ed25519 signature (for server-side delegated mode)
        timestamp:
          type: number
          description: Unix timestamp of delegation proof (must be within 60s)
          example: 1708700000
        paymentId:
          type: string
          description: Unique payment identifier (hex-encoded)
          example: a1b2c3d4e5f6
        txSignature:
          type: string
          description: On-chain transaction signature (for atomic/attestation modes)
          example: >-
            5VERv8NMvzbJMEkV8xnrLkEaWRtSz9CosKDYjCJjBRnbJLgp8uirBgmQpjKhoR4tjF3ZpRzrFmBV6UjKdiSZkQUW
        payer:
          type: string
          description: Payer wallet address
          example: D6j5dis544qzYmSNixwYwBXqcDqgWiFHpi6hebPEQNVu
        amount:
          type: string
          description: Payment amount in base units
          example: '1000000'
    PaymentRequirementsExtraDto:
      type: object
      properties:
        feePayer:
          type: string
          description: Facilitator public key that will co-sign as fee payer
          example: 7iRiHRnj1NofyEZVuj86Z4s5MJwVFZVR71XuAsLnwLYX
        name:
          type: string
          description: Human-readable name for the payment requirement
          example: Agent Query Fee
        agentMint:
          type: string
          description: x84 agent NFT mint address
          example: 6s1irFAQHoiK7VLwrUQEGpN5E1MrLoo5dZVWZCAwsDZS
        programId:
          type: string
          description: x84 program ID
          example: X84XHMKT7xvjgVUXFNQLZLSdCEEZu2wAPrAeP4M9Hhi
        settlementModes:
          description: Supported x84 settlement modes
          example:
            - atomic
            - attestation
            - delegated
          type: array
          items:
            type: string

````