feat: Implement x402 payment flow for PHP client

[ABEEGOLD]

Closes #48

PR Description: Minimal PHP Client & x402 Protocol Implementation

Description

This pull request introduces the first minimal implementation of the Nirium PHP SDK (packages/php-client), which adds full support for the x402 (Payment Required) protocol flow. It allows developers to seamlessly interact with API endpoints that require x402 payments (e.g., Nirium AI agents) and automate the underlying Soroban transaction logic directly in PHP.

Key Features

• Core X402Client: Intercepts 402 Payment Required HTTP responses from agents, extracts the required payment details (exact scheme), and automatically constructs and signs the proper transaction payload to satisfy the challenge.
• Soroban Transaction Building: Integrates the soneso/stellar-php-sdk for constructing the XDR representation of Soroban token transfers.
• Independent Auth Entry Signing: Addresses SDK limitations by dynamically constructing the transfer transaction using a dummy invoker during simulation. This ensures the resulting Soroban auth entries require a SOROBAN_CREDENTIALS_ADDRESS signature, allowing the PHP client to independently sign authorization payloads and hand them off to the agent without assuming the role of the invoker.
• Test Environment Support:
  • Provides a complete, containerized testing environment via Dockerfile to handle complex extension compilations (gmp, bcmath) needed by the underlying crypto libraries.
  • Extensively tests the 402 flow using GuzzleHttp\Handler\MockHandler and live Friendbot funding integrations to successfully validate testnet simulations.
• Examples: Includes a quick-start examples/pay.php demonstrating how to instantiate the client and fetch an agent URL.

Changes Included

• packages/php-client/composer.json: Added soneso/stellar-php-sdk, guzzlehttp/guzzle, and phpunit dependencies with PSR-4 autoloading.
• packages/php-client/src/X402Client.php: The main entrypoint for the HTTP client and Soroban integration.
• packages/php-client/tests/X402ClientTest.php: Complete unit test demonstrating successful flow handling, signature generation, and HTTP retries.
• packages/php-client/examples/pay.php: Sample script for executing the payment flow against an agent.
• packages/php-client/Dockerfile: A consistent testing environment.

Validation / Testing

• Testnet Simulation: The unit test successfully creates ephemeral accounts, funds them via Friendbot, and successfully passes Soroban testnet simulation (via simulateTransaction RPC) using real token contracts.
• Automated Tests: Tested using PHPUnit 11 within the provided Docker container. All assertions passed.

cd packages/php-client
docker build -t php-stellar-env .
docker run --rm -v $(pwd):/app -w /app php-stellar-env vendor/bin/phpunit tests/X402ClientTest.php

[Eras256]

Reviewed the actual source (X402Client.php, config, examples) — the payment flow itself is solid: correct x402 v2 handshake, correct PAYMENT-SIGNATURE header, correct x402Version: 2. Two things need fixing before this can merge:

1. vendor/ is committed to git. Of the ~3,800 changed lines, ~400 are third-party Composer dependencies checked straight into the repo (vendor/christian-riesen/base32, vendor/bin/phpunit, .phpunit.result.cache, etc.). Please add a .gitignore for vendor/ and remove it from the PR — only composer.json/composer.lock should be tracked; composer install regenerates the rest.

2. Transaction source account. X402Client::fetch() builds the AssembledTransaction with KeyPair::random() as the dummy invoker/source account, to avoid using the payer's own key as the tx source (correct instinct — using the payer's key there produces source-account credentials the facilitator can't honor). But this project's own working Python client uses a specific, proven null account for this (GAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAWHF — see packages/sdk-python/src/nirium/client.py), documented as "a template the facilitator re-issues with its own account to pay the fee." A random keypair may or may not be accepted the same way by the facilitator — worth confirming against a real testnet payment, or just switching to the same canonical null account the rest of the SDK uses, since that's already proven to work end-to-end.

Once vendor/ is out and the source-account question is resolved (or verified against a live testnet payment with a resolvable tx hash), happy to take another look.

[Eras256]

Reviewed the code, not just the description — three real issues, not merging yet.

1. vendor/ is committed — 100 files, ~682k lines added, including Composer's own dependency tree (vendor/christian-riesen/base32, vendor/composer/*, the phpunit binary itself). This should never be in git: add a .gitignore for vendor/ and document composer install in the README instead.

2. The transaction source account doesn't match the documented pattern. This client builds the AssembledTransaction with $dummyAccount from a freshly-random KeyPair::random() as the source, to avoid using the payer's own key as invoker — good instinct, wrong account. The reference pattern (see this repo's own Python client, packages/sdk-python/src/nirium/client.py, and the note in project docs) uses the canonical NULL account GAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAWHF specifically — it's a fixed, facilitator-recognized placeholder that the facilitator re-emits with its own account when it pays the fee. A random throwaway account each run isn't that same recognized identity, and using the payer's own account (the other wrong option) makes the simulator emit source-account credentials instead of the address credentials the facilitator can actually honor. Worth checking against a real facilitator whether the random-account version even gets ADDRESS-type credentials back from simulation.

3. Missing the re-simulate-after-signing step. The code simulates once, signs the auth entries, and sends — but the signature adds bytes to the transaction, so the resource fee computed before signing is too low (measured elsewhere in this project: 24127 vs. the correct 33735). The fix is a second simulateTransaction call after signing, using its corrected fee, before submitting — same pattern the merged Rust client (#66) and this repo's Python client both follow. Without it, expect payments to fail on-chain with an underpriced-resource-fee error even though the code compiles and the flow looks complete.

I wasn't able to run PHPUnit in this environment (no php binary available to me) — flagging that honestly rather than claiming a test result I don't have. Once 1–3 are addressed, happy to review again — the header handling (PAYMENT-SIGNATURE, correct base64 payload shape) is right, and this is close.

[ABEEGOLD]

@Eras256 This issue shows merged but still not recorded to me, can i know why??

[Eras256]

@ABEEGOLD sorry for the confusion — that's a real mixup, not you missing something.

Issue #48 got auto-closed by GitHub on 2026-08-24 because a different contributor's PR (#55, a Go client for issue #46) had a typo in its own description — "closes #48" instead of "closes #46" — and GrantFox's bot then credited that contributor for this issue by mistake, since it never actually did PHP work. I caught that and reopened #48 on 2026-08-26 with the explanation on the issue itself. If GrantFox's own board still shows it as completed/credited to someone else, that's the platform not having picked up the reopen — worth flagging directly on GrantFox too if it's still showing that way on your end.

You're still the assigned contributor here and #48 is open. Credit for it goes with whoever's PR actually lands — right now that's this PR, once it's ready.

On that: this PR itself hasn't moved since the review on 2026-08-26 — three things are still open before it can merge (quoting my own comment above so it's in one place):

1. vendor/ shouldn't be committed (~682k lines of Composer's own dependency tree) — add a .gitignore for it and document composer install instead.
2. The transaction source account should be the canonical NULL account (GAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAWHF), not a fresh random keypair — the facilitator specifically recognizes that placeholder.
3. Missing the re-simulate-after-signing step — the resource fee computed before signing is too low once the signature is added, so payments would fail on-chain with an underpriced-fee error even though it compiles.

Happy to review again as soon as those land.