Skip to main content
Solana settlement uses a direct SPL USDC transfer. When available, Gwop provides a fee payer so the paying agent does not need SOL for transaction fees. Endpoint: GET and POST /v1/invoices/{id}/x402/solana Asset: USDC on Solana (EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v) Network (CAIP-2): solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp

​
1. Discovery

GET /v1/invoices/{id}/x402/solana
Returns HTTP 402 with the PAYMENT-REQUIRED header (base64-encoded JSON): 
{
  "x402Version": 2,
  "error": "Payment required",
  "resource": {
    "method": "POST",
    "url": "https://agents.gwop.io/v1/invoices/{id}/x402/solana"
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
      "amount": "5000000",
      "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "payTo": "<merchant_solana_address>",
      "maxTimeoutSeconds": 900,
      "extra": {
        "invoiceId": "inv_...",
        "settlementId": "req_...",
        "assetSymbol": "USDC",
        "assetDecimals": 6,
        "chain": "solana",
        "feePayer": "<gwop_fee_payer_address>"
      }
    }
  ]
}

​
Key fields

FieldDescription
amountUSDC minor units (6 decimals). "5000000" = $5.00.
assetUSDC mint address on Solana.
payToMerchant’s Solana receive address.
maxTimeoutSecondsTime remaining before the settlement challenge expires.
extra.settlementIdRequired in the PAYMENT-SIGNATURE. Also used for recovery.
extra.feePayerGwop-provided fee payer address. If present, include as the fee payer in your transaction so the paying agent doesn’t need SOL for gas.

​
2. Payment signature

The client constructs a Solana transaction that transfers the specified amount of USDC from the payer to payTo. If extra.feePayer is provided, set it as the transaction’s fee payer. Two proof modes are supported: Sign and submit the transaction to the Solana network, then pass the transaction signature: 
{
  "x402Version": 2,
  "resource": {
    "method": "POST",
    "url": "https://agents.gwop.io/v1/invoices/{id}/x402/solana"
  },
  "accepted": {
    "scheme": "exact",
    "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
    "extra": {
      "settlementId": "req_..."
    }
  },
  "payload": {
    "tx_hash": "<solana_transaction_signature>"
  }
}

​
Option B: Submit serialized transaction

Submit the signed but unsubmitted transaction for the facilitator to broadcast: 
{
  "x402Version": 2,
  "resource": {
    "method": "POST",
    "url": "https://agents.gwop.io/v1/invoices/{id}/x402/solana"
  },
  "accepted": {
    "scheme": "exact",
    "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
    "extra": {
      "settlementId": "req_...",
      "feePayer": "<gwop_fee_payer_address>"
    }
  },
  "payload": {
    "transaction": "<base64_serialized_transaction>"
  }
}
Base64-encode the entire JSON object and send it as the PAYMENT-SIGNATURE header: 
POST /v1/invoices/{id}/x402/solana
PAYMENT-SIGNATURE: <base64>

​
Required payload fields

FieldTypeDescription
payload.tx_hashstringSolana transaction signature (if already submitted).
payload.transactionstringBase64-encoded serialized transaction (if not yet submitted).
accepted.extra.settlementIdstringThe settlementId from discovery.
accepted.extra.feePayerstringFee payer address (if using Gwop fee payer).
Provide either tx_hash or transaction, not both.

​
3. Settlement response

On success, the server returns HTTP 200 with the PAYMENT-RESPONSE header (base64-encoded JSON): 
{
  "x402Version": 2,
  "status": "settled",
  "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
  "txHash": "<solana_transaction_signature>",
  "settlementId": "req_..."
}
The response body includes the full paid invoice details: paid_at, paid_tx_hash, payer_address, paid_amount, and tx_url (Solscan link).

​
Fee payer

When extra.feePayer is present in the PAYMENT-REQUIRED response, Gwop provides a fee payer for the transaction. This means the paying agent does not need to hold SOL for gas fees. To use the fee payer:
  1. Set the feePayer field in your transaction to the address from extra.feePayer
  2. Sign the transaction with the payer’s keypair (partial sign — do not sign as fee payer)
  3. Submit the serialized transaction in payload.transaction
The facilitator co-signs and broadcasts the transaction. If you prefer to pay your own gas, ignore extra.feePayer, submit the transaction yourself, and pass the tx_hash in Option A.

​
Error diagnostics

Settlement errors return x402_diagnostics with a reason field:
ReasonMeaning
solana_transaction_invalidSerialized transaction is malformed or invalid.
solana_proof_mode_unsupportedProof mode not recognized.
resource_mismatchresource.url doesn’t match the endpoint.
chain_mismatchNetwork in signature doesn’t match /x402/solana.
verification_failedOn-chain verification failed (wrong amount, asset, or recipient).
payment_signature_replayedThis transaction signature was already used.
settlement_failedFacilitator could not settle the transaction.

​
Support

Having trouble with Solana x402 integration? Contact support@gwop.io with your invoice ID and we’ll help debug.